108 lines
5.1 KiB
Markdown
108 lines
5.1 KiB
Markdown
# 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.
|
|
- Turn log now returns populated actions and validation results per turn (previously always empty).
|
|
- Active rulebook ID is now persisted on worldState and survives restarts.
|
|
- `take` sets `has_<item_id>` generically on the actor (was hardcoded to key_1 only).
|
|
|
|
### Structural refactoring completed (April 2026)
|
|
|
|
- **Deleted `turns/processTurn.ts`** — was a 3-line shim over runTurnManager. app.ts now calls runTurnManager directly.
|
|
- **Deleted `truthEngine.ts`** — was a thin wrapper over rulebookEngine.validateWithRulebook. turnManager.ts now calls validateWithRulebook directly.
|
|
- **Extracted `world/seedWorld.ts`** — createSeedWorldState, mergeSeedWorldState, ensureSeedState moved out of app.ts. App factory is now clean.
|
|
- **Fixed `db.listTurns()`** — now reads back actions and validation_results from their tables. Frontend turn log now has real data.
|
|
- **Fixed `worldState.rulebookId` persistence** — upsertRulebook now updates worldState.rulebookId and persists a world snapshot so the active rulebook survives restarts.
|
|
- **Generalized `has_<item_id>` in applyActions** — `take` now sets `has_<item_id>` on the actor for all taken items, not just `key_1`. The attributeRef rulebook check continues to work generically.
|
|
|
|
### 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
|
|
|
|
1. Rulebook externalization
|
|
- Pulling edge-case logic out of hardcoded truth engine branches was the right move.
|
|
- It now supports editable policy without code deployment.
|
|
|
|
2. Explicit authorization checks in rules
|
|
- Authorization for creation-style actions now belongs to policy, not parser guesswork.
|
|
- This aligns with deterministic governance.
|
|
|
|
3. Introducing transfer as first-class action
|
|
- This avoids overloading take semantics and keeps intent/action boundaries cleaner.
|
|
|
|
4. Turn manager seam
|
|
- processTurn delegating to a turn manager creates a stable orchestration point for interpreter upgrades.
|
|
|
|
### Risks / cleanup still needed
|
|
|
|
1. Frontend contract drift risk
|
|
- App.tsx has historically duplicated blocks during rapid edits.
|
|
- Keep one canonical component and avoid append-style merges.
|
|
|
|
2. Interpreter observability depth
|
|
- Interpreter traces are persisted, but aggregate analytics/counters are still missing.
|
|
|
|
3. Rulebook migration strategy
|
|
- Existing DBs may hold older rulebooks missing new action rule sets.
|
|
- Need explicit upgrade path/versioning.
|
|
|
|
4. Parser is world-specific
|
|
- parseTextToActions.ts hardcodes entity IDs (room_exit, door_1, key_1, groundskeeper).
|
|
- The parser is used only inside the deterministic resolver adapter; keeping it isolated limits blast radius, but a future world-context-aware resolver would eliminate this entirely.
|
|
|
|
5. Entity table vs world_state blob redundancy
|
|
- `entities` table and `world_states.state_json` both store entity data. The entities table is the live read target; world_states is the history log. No query capability on history. Acceptable for MVP.
|
|
|
|
## 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.
|