spencer
fc10e46ccc
- Added new contracts for intent interpretation, including InterpreterOutput and ResolverMode. - Implemented deterministic intent resolver with clarity checks for ambiguous references and empty input. - Developed LLM intent resolver that communicates with an external model, handling JSON responses and fallback clarifications. - Created an interpretTurn function to manage intent resolution based on the selected resolver mode. - Introduced validation for interpreter output to ensure integrity before processing actions. - Established a turn manager to orchestrate turn processing, including action validation and world state mutation. - Added integration tests to verify the functionality of the new intent resolution system. Co-authored-by: Copilot <copilot@github.com>
3.3 KiB
3.3 KiB
thoughts.md
Documentation Sync
- Implementation plan refreshed in Implementation_plan.md to match current codebase state.
- Next executable phase is Phase 1: Intent Interpreter Boundary Hardening.
Current Snapshot (April 2026)
What is now working
- Rulebook-driven validation is active and editable through API/frontend.
- Character authorization rules are in place (actorIdIn / actorNameIn).
- take supports createIfMissing, gated by rulebook permissions.
- transfer action is live with ownership + recipient + location validation.
- Turn processing now goes through a dedicated turn manager layer.
- Intent interpreter contract exists with resolved / needs_clarification / rejected statuses.
- Interpreter envelopes are persisted per turn and surfaced to the UI timeline.
- LLM resolver now calls an HTTP model backend (Ollama-compatible) with hybrid deterministic fallback.
- Rulebooks now include a version field with backward-compatible DB migration.
Confirmed via containerized validation
- Backend build passes in Docker:
- docker compose run --rm app npm run build
- Frontend build passes in Docker:
- docker compose run --rm frontend npm run build
- Host Node build is intentionally not relied on.
Architecture Feedback
Good decisions worth keeping
- Rulebook externalization
- Pulling edge-case logic out of hardcoded truth engine branches was the right move.
- It now supports editable policy without code deployment.
- Explicit authorization checks in rules
- Authorization for creation-style actions now belongs to policy, not parser guesswork.
- This aligns with deterministic governance.
- Introducing transfer as first-class action
- This avoids overloading take semantics and keeps intent/action boundaries cleaner.
- Turn manager seam
- processTurn delegating to a turn manager creates a stable orchestration point for interpreter upgrades.
Risks / cleanup still needed
- Frontend contract drift risk
- App.tsx has historically duplicated blocks during rapid edits.
- Keep one canonical component and avoid append-style merges.
- Interpreter observability depth
- Interpreter traces are persisted, but aggregate analytics/counters are still missing.
- Rulebook migration strategy
- Existing DBs may hold older rulebooks missing new action rule sets.
- Need explicit upgrade path/versioning.
Path Forward (Next 3 Iterations)
Iteration 1: LLM adapter hardening
- Harden prompt + response schema handling for model drift and malformed JSON.
- Add environment-specific model/timeouts and failure policy guidance.
- Add tests covering unavailable model backend and malformed payload fallback.
Iteration 2: Traceability + observability
- Surface interpreter status in frontend turn log.
- Add reason-code analytics counters for failed validations and unresolved intents.
Iteration 3: Rulebook lifecycle and test harness
- Add policy packs (creation, transfer, social).
- Add Docker-run integration tests for:
- unauthorized createIfMissing
- authorized createIfMissing
- transfer success/failure matrix
- clarification path for ambiguous/unrecognized input
Operating Guidance
- Keep all build/test checks containerized.
- Treat interpreter as replaceable adapter behind a stable contract.
- Keep truth engine deterministic and side-effect free.
- Keep mutation logic pure relative to validated actions only.