feat: complete Tiny Stories research runtime

README.md

@@ -54,6 +54,10 @@
   ·
   <a href="https://lishehao.github.io/RPG_Demo/app/#/demo/reviewer"><strong>Open public reviewer demo</strong></a>
   ·
+  <a href="./docs/RPG_EVALUATION_LAB.md"><strong>RPG evaluation lab</strong></a>
+  ·
+  <a href="https://tiny-stories-rpg-evaluation.vercel.app"><strong>Open deployed evaluation lab</strong></a>
+  ·
   <a href="./docs/demo-video/tiny-stories-admissions-demo-readme.mp4">Open MP4 demo</a>
   ·
   <a href="./docs/CURRENT_SYSTEM_MAP.md">Inspect source evidence</a>
@@ -66,6 +70,14 @@ source, tests, reviewer run, and system map.
 The public reviewer demo is a deterministic GitHub Pages app path: no API key,
 no live backend, and no generation claim beyond the committed source evidence.
 
+The [RPG Runtime Evaluation Lab](./docs/RPG_EVALUATION_LAB.md) adds a portable,
+backend-free reviewer surface for comparing another RPG agent's memory,
+consequences, agency, trajectory, entities, choices, and player-facing boundary
+hygiene through `rpg_evaluation_bundle.v1`. It is a deterministic diagnostic,
+not a calibrated academic metric.
+
+Public deployment: <https://tiny-stories-rpg-evaluation.vercel.app>
+
 ---
 
 ## Reviewer Run

README.zh.md

@@ -50,10 +50,17 @@
 - [观看 75 秒 demo](https://youtu.be/RRJ7uyjW_nA)
 - [打开 MP4 备份](./docs/demo-video/tiny-stories-admissions-demo-readme.mp4)
 - [公开链接检查通过后再打开 GitHub Pages 展示页](https://lishehao.github.io/RPG_Demo/)
+- [查看 RPG Runtime Evaluation Lab 接入规范](./docs/RPG_EVALUATION_LAB.md)
+- [打开已部署的 RPG Runtime Evaluation Lab](https://tiny-stories-rpg-evaluation.vercel.app)
 
 视频用于快速理解玩家看到的 loop;真正的申请材料证据仍然在 source、tests、
 `#/portfolio`、`#/reviewer`、system map 和 engineering evidence packet 里.
 
+RPG Runtime Evaluation Lab 是一个不依赖后端的公开评测前端。其他 RPG Agent
+只需输出 `rpg_evaluation_bundle.v1`,即可用同一界面检查记忆连续性、后果可见性、
+玩家能动性、目标推进、人物一致性、选择多样性和边界卫生。该分数是确定性产品诊断,
+不是已经校准的学术质量指标。
+
 如果要把公开链接发给招生、推荐人或招聘 reviewer,先运行公开链接检查:
 `python3 tools/portfolio_public_evidence_preflight.py`.如果它提示本地 `HEAD`
 领先 `origin/main`,或 GitHub Pages 缺少当前 marker,这些证据只能算

docs/RESEARCH_RUNTIME_BRIEF.md

@@ -0,0 +1,97 @@
+# Tiny Stories Research Runtime Brief
+
+## Decision
+
+Tiny Stories is scoped as a research-grade technical product:
+
+> A controllable and evaluated LLM interactive-narrative runtime, delivered as
+> a research specification, a runnable reference implementation, and a
+> repeatable evaluation harness.
+
+Interactive storytelling is the experimental carrier. The project does not
+claim consumer-market validation, general narrative robustness, or a novel
+foundation model.
+
+## Primary Question
+
+How can an underspecified, revisable user intent be compiled into a bounded,
+stateful, playable, recoverable, and evaluable interactive narrative under
+stochastic LLM outputs?
+
+## Approved Defaults
+
+1. Primary audience: applied-AI R&D, product-systems, and graduate-project reviewers.
+2. Secondary audience: interactive-narrative creators and bounded test participants.
+3. Public delivery: static evidence and evaluation UI, with invite-controlled or quota-bounded live runs.
+4. Content boundary: a small set of modern social-pressure, backstage, workplace, and mystery scenarios.
+5. Evidence: deterministic fixtures, bounded live-provider acceptance, structured judges, and small formative human review.
+6. Provider strategy: one primary live provider with only bounded comparison runs.
+7. Post-research direction: freeze evidence first; reopen consumer beta or creator SDK only if the research reveals a clear opportunity.
+
+## In Scope
+
+- arbitrary-input Story Butler routing and compressed context;
+- corrections and superseded-fact handling;
+- Story Brief compilation and opening fidelity;
+- a 12-turn playable runtime with explicit goals, pressure, people, clues, forecasts, and impacts;
+- bounded failure, retry, repair, fallback, idempotency, and persistence;
+- reviewer-only telemetry and deterministic/LLM-assisted evaluation;
+- Chinese/English and desktop/mobile robustness;
+- a portable RPG evaluation bundle and public evaluation frontend.
+
+## Explicit Non-goals
+
+- open UGC marketplace;
+- deep emotional-companion positioning;
+- adult visual content;
+- subscriptions, growth loops, or consumer retention claims;
+- multiplayer/social graph;
+- production-scale multi-tenant infrastructure;
+- calibrated academic metrics or SOTA claims.
+
+## Completion Evidence
+
+The research artifact is complete only when a third party can:
+
+1. understand the claim and its limits;
+2. inspect a deterministic success and failure case;
+3. run a bounded live path with real telemetry;
+4. inspect memory, state, consequences, and evaluator evidence;
+5. reproduce the tests and static public demo without secrets.
+
+## Reference Data Path
+
+```text
+arbitrary input
+  -> intent-aware Story Butler
+  -> bounded current-truth memory
+  -> Story Brief
+  -> persisted template research context
+  -> live opening
+  -> 12-turn Action Runtime
+  -> ending
+  -> portable session bundle
+  -> deterministic evaluator + Reviewer evidence
+```
+
+Corrections are first-class events: the replacement becomes active truth while
+the old value remains only in `superseded_facts`. Play and ending prompts use a
+sanitized Story Contract rather than the unbounded Create transcript. The
+portable evaluator receives explicit terminal-turn and progress-provenance
+fields so it can distinguish runtime facts from turn-budget proxies.
+
+The public Vercel lab is deliberately static and backend-free. Live acceptance
+is proven separately through a configured local gateway, strict telemetry, and
+a 12-turn golden-path artifact. This division keeps the demo reproducible while
+preventing a static portfolio surface from being mistaken for live-provider
+evidence.
+
+## Current Reference Acceptance
+
+As of 2026-08-24, the strict reference run completes a corrected Story Butler
+conversation, Story Brief, live opening, 12 live Play turns, ending, persisted
+session export, Reviewer evidence, and portable evaluation with no required
+operation falling back. English and Chinese bounded runs verify that current
+facts, superseded corrections, story language, and responsive UI state survive
+the same chain. The full records live under `docs/evidence/` and intentionally
+retain latency, token, source, fallback, provenance, and consistency caveats.

docs/RPG_EVALUATION_LAB.md

@@ -0,0 +1,201 @@
+# RPG Runtime Evaluation Lab
+
+## Purpose
+
+The RPG Runtime Evaluation Lab is a backend-free reviewer frontend for
+comparing stateful RPG-agent runs. It is intentionally broader than Tiny
+Stories: another RPG can export one portable JSON bundle and use the same
+memory, consequence, agency, trajectory, entity, choice, and boundary checks.
+
+Public route:
+
+```text
+#/lab/rpg-evaluation
+```
+
+Public deployment: <https://tiny-stories-rpg-evaluation.vercel.app>
+
+The lab is a product reliability diagnostic. Its score is deterministic and
+inspectable, but it is not a calibrated academic quality metric. Narrative
+appeal and emotional quality still require bounded human review.
+
+## Portable Contract
+
+The input root is `rpg_evaluation_bundle.v1`:
+
+```json
+{
+  "schema_version": "rpg_evaluation_bundle.v1",
+  "run_id": "run-123",
+  "system_label": "Candidate runtime",
+  "locale": "en",
+  "scenario": {
+    "scenario_id": "backstage-01",
+    "title": "Vanished Before Curtain",
+    "genre": "social-pressure mystery",
+    "objective": "Find the singer before air.",
+    "turn_budget": 12,
+    "entity_ids": ["singer", "producer", "publicist"],
+    "boundaries": ["No violence"]
+  },
+  "turns": []
+}
+```
+
+Each turn contains:
+
+- the player action;
+- the player-visible world response;
+- the real next-action set;
+- typed state deltas;
+- clue and opportunity unlocks;
+- referenced entity ids;
+- bounded objective progress;
+- one `rpg_memory.v1` snapshot.
+
+The frontend deliberately does not accept raw prompts, private reasoning,
+provider credentials, or tool arguments.
+
+## Memory Contract
+
+`rpg_backend.research_runtime.memory` reduces portable events into a bounded,
+auditable snapshot:
+
+- active facts have one current value per namespace/key;
+- corrections move the previous value to `superseded_facts`;
+- non-story input is retained as conversational evidence but never becomes a
+  story fact;
+- open threads can be opened and resolved;
+- person state is merged by entity id;
+- recent events and active facts have explicit budgets;
+- diagnostics report event, active, superseded, non-story, dropped, and
+  compaction counts.
+
+`project_story_guide_memory()` projects the existing Story Butler compressed
+context into the same portable contract. The live Story Butler prompt and
+runtime behavior remain unchanged.
+
+## Deterministic Criteria
+
+| Criterion | What it checks |
+| --- | --- |
+| Memory continuity | No duplicate active fact or active/superseded conflict |
+| Memory boundedness | Fact and recency budgets remain bounded |
+| Consequence visibility | Each move yields a typed delta, clue, or opportunity |
+| Player agency | Each turn preserves at least two distinct next actions |
+| Trajectory progress | Objective progress advances without unexplained regression |
+| Entity coherence | Referenced people/factions exist in the scenario registry |
+| Choice diversity | Full next-action sets change across the trajectory |
+| Boundary hygiene | Player text contains no protocol or private-reasoning leakage |
+
+The aggregate score is a readable summary, not a replacement for criterion
+rows or evidence.
+
+## CLI
+
+Export a bundle from the lab, then run the same backend evaluator:
+
+```bash
+python3.11 -m tools.rpg_eval.portable_runtime run.json --out report.json
+```
+
+No provider call is made. Invalid or extra fields fail closed through Pydantic
+contracts.
+
+## Frontend Views
+
+- **Overview**: aggregate result, criterion rows, evidence, and baseline comparison.
+- **Run trace**: action, world reaction, explicit changes, and next actions per turn.
+- **Memory**: active facts, superseded facts, people, open threads, and recent events.
+- **Adapter**: compact input shape plus bundle/report downloads.
+
+The built-in candidate and prose-only baseline make the lab usable without a
+backend. Imported bundles never leave the browser.
+
+When the full local Tiny Stories backend is running, the same route also accepts
+`?session=<session_id>`. An authenticated owner can load a completed live
+session, export its server-built bundle, and run the authoritative deterministic
+evaluator without copying JSON. This local-only loader is omitted from the
+public static build, so the Vercel artifact remains backend-free and cannot
+silently claim access to live sessions.
+
+## End-to-End Provenance
+
+The reference runtime keeps one auditable contract across the product chain:
+
+1. Story Butler compacts current facts, corrections, boundaries, open questions,
+   and non-story intents.
+2. Template creation persists the Story Brief plus a sanitized Story Guide
+   context. Raw chat turns are not stored in this research seed.
+3. Play turns and endings receive a compact `story_contract` containing current
+   truth only. Superseded facts, meta conversation, planner internals, and raw
+   model messages are excluded.
+4. Session export projects the persisted seed and every completed Play turn into
+   `rpg_evaluation_bundle.v1`.
+5. The frontend lab and backend evaluator share the same terminal-turn and
+   progress-provenance rules. A reported progress value derived from the turn
+   budget is labeled `turn_budget_proxy`, not presented as engine ground truth.
+
+The owner-only Reviewer surface links to the session-scoped lab after the first
+completed turn. Normal Play remains free of evaluator, token, provider, and
+private-reasoning details.
+
+## Vercel Delivery
+
+`frontend2/vercel.json` builds the same React application with
+`VITE_PUBLIC_LAB_DEFAULT=true`. The deployment therefore opens the evaluation
+lab at the root and skips the initial auth request. No LLM key or backend URL is
+needed for the public artifact.
+
+The live Tiny Stories acceptance path remains a separate, configured-backend
+validation. A static Vercel demo must not be cited as live-provider proof.
+
+## Strict Live Gate
+
+`tools/rpg_eval/tiny_stories_golden_path_harness.py` is the strict completion
+gate. It runs a corrected Story Butler memory sequence, Story Brief, live
+opening, 12 live Play turns, ending, persisted session export, and backend
+evaluation. Every required provider operation must be `live` or
+`live_repaired`, with no fallback reason. The gate preserves exact telemetry
+and a deterministic quality summary; neither is a substitute for human
+narrative judgment.
+
+## Latest Bounded Live Acceptance
+
+The strict 2026-08-24 run used an isolated runtime database and a configured
+live text gateway. It corrected an initially wrong player role, compiled the
+current truth into a Story Brief, generated a live opening, completed all 12
+Play turns, produced an ending, exported the persisted session, and evaluated
+the portable bundle. The sanitized evidence is available as
+[`evidence/tiny-stories-12-turn-live-research-runtime-2026-08-24.json`](./evidence/tiny-stories-12-turn-live-research-runtime-2026-08-24.json)
+and a compact
+[`Markdown report`](./evidence/tiny-stories-12-turn-live-research-runtime-2026-08-24.md).
+
+| Gate | Result |
+| --- | --- |
+| Required live operations | Story Butler, Story Brief, Opening, 12 Play turns |
+| Provider classification | all `live/success`; zero fallback, repair, or retry |
+| Play latency | 11,403 ms median; 14,858 ms max |
+| Play usage | 99,705 input; 71,680 cached input; 7,665 output; 107,370 total tokens |
+| Ending | completed at 12/12, canonical label `共谋` |
+| Step / Contract Judge | 12 / 12 rows, all pass |
+| Deterministic quality package | all 6 bounded criteria pass |
+| Portable evaluator | pass, 100/100, progress provenance `turn_budget_proxy` |
+| Memory | 13 active facts; 3 superseded facts; corrected role absent from current truth |
+
+Two shorter bilingual runs separately exercise the same current-truth memory,
+Brief, opening, Play, persistence, and evaluator path:
+
+- [English live acceptance](./evidence/rpg-evaluation-live-memory-acceptance-2026-08-24.json):
+  pass, portable score 90, opening consistency pass.
+- [Chinese live acceptance](./evidence/rpg-evaluation-live-zh-acceptance-2026-08-24.json):
+  pass, portable score 90, Chinese Story Butler/Brief/Opening/Play output, opening
+  consistency warn retained as a quality limitation.
+
+These runs prove that the bounded reference path can complete through the
+configured provider without deterministic fallback. They do not prove general
+story quality, calibrated fun, consumer demand, or robustness outside the
+tested scenarios. The Browser acceptance also covered English and Chinese
+Home, Create, Play, Replay, Portfolio, About, Evaluation, Reviewer, and local QA
+routes at desktop and 390 px widths; normal player surfaces had no provider,
+schema, token, trace, fallback, raw JSON, or private-reasoning copy.