CharacterGardenStack/thoughts.md

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.