xrefkit 0.4.16__tar.gz → 0.5.1__tar.gz

{xrefkit-0.4.16/xrefkit.egg-info → xrefkit-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xrefkit
-Version: 0.4.16
+Version: 0.5.1
 Summary: Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit
 Author: synthaicode
 License: MIT License
@@ -42,11 +42,44 @@ Dynamic: license-file
 XRefKit is a framework for making AI-assisted work repeatable, reviewable, and
 handoff-ready.
 
-It helps teams turn domain procedures and knowledge into work that can be
-performed with explicit evidence, human judgment, and completion checks.
+It helps teams structure domain procedures and knowledge so that work can
+record evidence, preserve human judgment, and apply explicit completion checks.
 
 ## Why XRefKit?
 
+Experimental local tool: [Attention Pet](projects/attention-pet/README.md) helps
+people assess capability sufficiency and lower inference-cost candidates separately.
+Its Model Fit / Cost Fit estimates use uncalibrated profiles; it does not measure internal
+attention or switch models automatically.
+
+### Codex-only preview: Attention Pet
+
+Attention Pet is a small local companion for Codex work. It reads the current
+Codex chat's local session record, estimates whether the selected model meets
+the visible work requirements, and shows the result through a compact animated
+pet. It also shows lower inference-cost comparison candidates when the
+experimental profiles support one. The estimate is observational and does not
+change the Codex model, reasoning level, or chat.
+
+Run it from a Codex terminal in this repository so `CODEX_THREAD_ID` identifies
+the current chat:
+
+```powershell
+python -m xrefkit.attention_pet serve --port 8769
+```
+
+Open the printed `http://127.0.0.1:8769/` address in the Codex browser panel.
+The display follows the browser's preferred language: Japanese is used for a
+Japanese preference, with English as the fallback. Stop the process with
+Ctrl+C.
+
+This Codex preview is bound to the chat that launched it. Selecting another
+chat does not move the Pet automatically; launch it again from that chat when
+you want a separate view. The model and reasoning dropdowns only compare
+estimates and do not change the active Codex settings. See the
+[Attention Pet guide](projects/attention-pet/README.md) for interpretation,
+limitations, client integration, and API details.
+
 Using AI for real work creates recurring operating problems:
 
 ![Why XRefKit is needed](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)
@@ -61,24 +94,34 @@ XRefKit provides a repository and runtime model for addressing these problems.
 
 ## What it provides
 
-- **Skills** — reusable procedures for a defined kind of work
-- **Knowledge** — source-backed domain facts and local rules
-- **Workflow protocol** — recorded progress, deterministic verification, and
-  closure checks
+- **Skills** — reusable procedures expressed as SkillDefinitions
+- **Knowledge** — source-backed domain facts and local rules resolved by XID
+  when a Skill run needs them
+- **Workflow protocol** — recorded progress, deterministic workflow-record
+  verification, and closure checks
 - **Evidence and handoffs** — outputs, judgments, concerns, and decisions that
   remain reviewable after the work is done
-- **Skill Run Dashboard** — inspect Skill execution status, referenced XIDs,
-  evidence, judgments, concerns, and handoffs to improve the auditability of
-  results
+- **Skill Run Dashboard** — inspect recorded Skill execution state, definition
+  identity, runtime binding, referenced XIDs, evidence, judgments, concerns,
+  and handoffs
 - **XIDs** — stable references for connecting procedures, knowledge, and
   supporting documents
 
 The package includes the resolver, Skill runtime, workflow controls, client
 tools, and an optional MCP adapter.
 
+Current Skill authoring targets the one-document `skill_definition_v1` format.
+Existing `legacy_split_v1` Skills and unversioned historical run logs remain
+readable during migration. The [Workflow Runtime Binding](docs/core/contracts/111_workflow_runtime_binding.md#xid-8D50A972BA9F)
+defines how instruction-derived `capability`, `tuning`, `responsibility`, and
+`execution_mode` are captured; these are not fixed SkillDefinition properties.
+Knowledge used by a Skill remains separate and is resolved from the XID catalog
+when needed.
+
 The [Skill Run Dashboard](docs/guides/086_skill_run_observation_dashboard_usage.md#xid-4A4763A2DE63)
-helps people trace how a Skill run used its referenced XIDs and recorded its
-evidence before accepting or handing off the result.
+helps people inspect recorded XID retrieval and use together with the run's
+evidence before a human accepts or hands off the result. The Dashboard reports
+recorded state and missing observations; it does not accept output quality.
 
 ## Quick start
 
@@ -104,12 +147,17 @@ python -m pip install "xrefkit[mcp]"
 xrefkit mcp serve --repo . --transport stdio
 ```
 
+This command starts the optional catalog and runtime MCP adapter. This checkout
+does not implement management upload, staging, sealing, review, or adoption of
+uploaded SkillDefinition bytes into the active catalog.
+
 ## Where to go next
 
 - [Install XRefKit and register Skill Packages](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90)
 - [Understand the workflow protocol](docs/guides/087_workflow_protocol_sequence_for_humans.md#xid-E8B4D2F19A63)
 - [Use an instruction-backed workflow](docs/guides/088_instruction_workflow_protocol.md#xid-9F4C2A7D1B60)
 - [Understand Skills and Knowledge](docs/core/models/052_flow_capability_skill_knowledge_model.md#xid-91C4B7E2D5A8)
+- [Read the SkillDefinition v1 contract](docs/core/contracts/096_skill_definition_contract.md#xid-E6A19D4B72C3)
 - [Author a Skill with xref](docs/guides/013_skill_authoring_with_xref.md#xid-3DB05A0F5F5B)
 - [Browse the complete documentation index](docs/000_index.md#xid-56DD6EB68343)
 

xrefkit-0.5.1/README.md

@@ -0,0 +1,130 @@
+# XRefKit
+
+XRefKit is a framework for making AI-assisted work repeatable, reviewable, and
+handoff-ready.
+
+It helps teams structure domain procedures and knowledge so that work can
+record evidence, preserve human judgment, and apply explicit completion checks.
+
+## Why XRefKit?
+
+Experimental local tool: [Attention Pet](projects/attention-pet/README.md) helps
+people assess capability sufficiency and lower inference-cost candidates separately.
+Its Model Fit / Cost Fit estimates use uncalibrated profiles; it does not measure internal
+attention or switch models automatically.
+
+### Codex-only preview: Attention Pet
+
+Attention Pet is a small local companion for Codex work. It reads the current
+Codex chat's local session record, estimates whether the selected model meets
+the visible work requirements, and shows the result through a compact animated
+pet. It also shows lower inference-cost comparison candidates when the
+experimental profiles support one. The estimate is observational and does not
+change the Codex model, reasoning level, or chat.
+
+Run it from a Codex terminal in this repository so `CODEX_THREAD_ID` identifies
+the current chat:
+
+```powershell
+python -m xrefkit.attention_pet serve --port 8769
+```
+
+Open the printed `http://127.0.0.1:8769/` address in the Codex browser panel.
+The display follows the browser's preferred language: Japanese is used for a
+Japanese preference, with English as the fallback. Stop the process with
+Ctrl+C.
+
+This Codex preview is bound to the chat that launched it. Selecting another
+chat does not move the Pet automatically; launch it again from that chat when
+you want a separate view. The model and reasoning dropdowns only compare
+estimates and do not change the active Codex settings. See the
+[Attention Pet guide](projects/attention-pet/README.md) for interpretation,
+limitations, client integration, and API details.
+
+Using AI for real work creates recurring operating problems:
+
+![Why XRefKit is needed](human-docs/en/assets/why_xrefkit_needed/whatis_xrefkit.png)
+
+- the AI can act from incomplete context or unsupported guesses
+- procedures, domain facts, and judgment criteria get mixed together in prompts
+- execution, checking, and handoff collapse into one opaque step
+- work becomes hard to continue across agents, humans, or sessions
+- outputs may lack evidence, closure discipline, or auditability
+
+XRefKit provides a repository and runtime model for addressing these problems.
+
+## What it provides
+
+- **Skills** — reusable procedures expressed as SkillDefinitions
+- **Knowledge** — source-backed domain facts and local rules resolved by XID
+  when a Skill run needs them
+- **Workflow protocol** — recorded progress, deterministic workflow-record
+  verification, and closure checks
+- **Evidence and handoffs** — outputs, judgments, concerns, and decisions that
+  remain reviewable after the work is done
+- **Skill Run Dashboard** — inspect recorded Skill execution state, definition
+  identity, runtime binding, referenced XIDs, evidence, judgments, concerns,
+  and handoffs
+- **XIDs** — stable references for connecting procedures, knowledge, and
+  supporting documents
+
+The package includes the resolver, Skill runtime, workflow controls, client
+tools, and an optional MCP adapter.
+
+Current Skill authoring targets the one-document `skill_definition_v1` format.
+Existing `legacy_split_v1` Skills and unversioned historical run logs remain
+readable during migration. The [Workflow Runtime Binding](docs/core/contracts/111_workflow_runtime_binding.md#xid-8D50A972BA9F)
+defines how instruction-derived `capability`, `tuning`, `responsibility`, and
+`execution_mode` are captured; these are not fixed SkillDefinition properties.
+Knowledge used by a Skill remains separate and is resolved from the XID catalog
+when needed.
+
+The [Skill Run Dashboard](docs/guides/086_skill_run_observation_dashboard_usage.md#xid-4A4763A2DE63)
+helps people inspect recorded XID retrieval and use together with the run's
+evidence before a human accepts or hands off the result. The Dashboard reports
+recorded state and missing observations; it does not accept output quality.
+
+## Quick start
+
+XRefKit requires Python 3.11 or later.
+
+```powershell
+python -m pip install xrefkit
+xrefkit init
+xrefkit --help
+```
+
+For local development:
+
+```powershell
+python -m pip install -e .
+xrefkit init
+```
+
+For the optional MCP server:
+
+```powershell
+python -m pip install "xrefkit[mcp]"
+xrefkit mcp serve --repo . --transport stdio
+```
+
+This command starts the optional catalog and runtime MCP adapter. This checkout
+does not implement management upload, staging, sealing, review, or adoption of
+uploaded SkillDefinition bytes into the active catalog.
+
+## Where to go next
+
+- [Install XRefKit and register Skill Packages](docs/guides/089_xrefkit_package_first_registration.md#xid-4F8C2A7D1E90)
+- [Understand the workflow protocol](docs/guides/087_workflow_protocol_sequence_for_humans.md#xid-E8B4D2F19A63)
+- [Use an instruction-backed workflow](docs/guides/088_instruction_workflow_protocol.md#xid-9F4C2A7D1B60)
+- [Understand Skills and Knowledge](docs/core/models/052_flow_capability_skill_knowledge_model.md#xid-91C4B7E2D5A8)
+- [Read the SkillDefinition v1 contract](docs/core/contracts/096_skill_definition_contract.md#xid-E6A19D4B72C3)
+- [Author a Skill with xref](docs/guides/013_skill_authoring_with_xref.md#xid-3DB05A0F5F5B)
+- [Browse the complete documentation index](docs/000_index.md#xid-56DD6EB68343)
+
+## Security
+
+XRefKit does not require provider API keys to explore or install the package.
+Do not commit secrets, API keys, access tokens, `.env` files, or provider
+credentials. Authenticate external AI tools through their official provider
+mechanisms.

{xrefkit-0.4.16 → xrefkit-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xrefkit"
-version = "0.4.16"
+version = "0.5.1"
 description = "Portable XID, Skill, Knowledge, workflow, and MCP runtime for XRefKit"
 readme = "README.md"
 requires-python = ">=3.11"

xrefkit-0.5.1/tests/test_artifact_selected_family.py

@@ -0,0 +1,46 @@
+from pathlib import Path
+
+import pytest
+
+from xrefkit.mcp.catalog import XRefCatalog
+from xrefkit.skill_definition import load_skill_definition
+
+
+CASES = [
+    ("xlsx_spec_traceability", "xlsx_spec_traceability", "A7C3E9D2F610", "2D1B6A9E7C40", "5A7C2D4E9130"),
+    ("marketing-explainer-video", "marketing_explainer_video", "B8F1A6C4D720", "5E147B19D33D", "A6B923E41178"),
+    ("marketing_slide_png", "marketing_slide_png", "C2E7B9F5A130", "91B67D4AC2F3", "5E2C4A90D711"),
+    ("import_skill", "import_skill", "D5A8C1E6B740", "7C2A492D2B72", "1DF4555E1B02"),
+]
+
+
+@pytest.mark.parametrize("directory,skill_id,xid,body_xid,meta_xid", CASES)
+def test_artifact_v1_parse_concrete_metadata_and_legacy(directory, skill_id, xid, body_xid, meta_xid):
+    repo = Path(__file__).resolve().parents[1]
+    relative = Path(f"skills/{directory}/SKILL.v1.md")
+    definition = load_skill_definition(repo / relative)
+    metadata = definition["metadata"]
+    assert metadata["skill_id"] == skill_id
+    assert metadata["xid"] == xid
+    assert set(metadata["aliases"]) == {body_xid, meta_xid}
+    assert metadata["inputs"] and metadata["outputs"]
+    assert metadata["control_refs"] == []
+    assert "CAP-" not in definition["method"]
+    assert "## Reporting Contract" not in definition["method"]
+    assert "skill_doc: `./SKILL.md`" in (repo / relative.parent / "meta.md").read_text()
+
+
+def test_artifact_v1_explicit_batch_selection_and_knowledge_resolution():
+    repo = Path(__file__).resolve().parents[1]
+    paths = [Path(f"skills/{directory}/SKILL.v1.md") for directory, *_ in CASES]
+    catalog = XRefCatalog.build(repo, skill_definition_paths=paths)
+    ids = {case[1] for case in CASES}
+    entries = {entry.skill_id: entry for entry in catalog.skills if entry.skill_id in ids}
+    assert set(entries) == ids
+    assert all(entry.definition_format == "skill_definition_v1" for entry in entries.values())
+    for directory, skill_id, *_ in CASES:
+        definition = load_skill_definition(repo / f"skills/{directory}/SKILL.v1.md")
+        need_ids = [need["id"] for need in definition["metadata"]["knowledge_needs"]]
+        result = catalog.resolve_skill_knowledge(skill_id, need_ids)
+        assert result["unresolved_activation"] == []
+        assert result["unsatisfied_required"] == []

xrefkit-0.5.1/tests/test_attention_pet.py

@@ -0,0 +1,257 @@
+import json
+import threading
+from urllib.error import HTTPError
+from urllib.request import Request, urlopen
+
+import pytest
+from pydantic import ValidationError
+
+from xrefkit.attention_pet.evaluator import Weights, evaluate
+from xrefkit.attention_pet.model import Conversation, Edge, Item, WorkingSet, extract
+from xrefkit.attention_pet.scenarios import scenario
+from xrefkit.attention_pet.server import make_server
+from xrefkit.attention_pet.store import Store
+
+
+def fixture(name="A", step=1):
+    return WorkingSet.model_validate(scenario(name, step)["workingSet"])
+
+
+def test_scenario_a_independent_requests_grow_gradually():
+    scores = [evaluate(fixture("A", s))["ral"] for s in range(1, 6)]
+    assert scores == sorted(scores)
+    assert max(b - a for a, b in zip(scores, scores[1:])) < 10
+
+
+def test_scenario_b_relationships_cost_more_than_independent_items():
+    a, b = evaluate(fixture("A", 5)), evaluate(fixture("B", 5))
+    assert a["features"]["active_items"] == b["features"]["active_items"]
+    assert b["ral"] > a["ral"] + 20
+    assert b["features"]["dependency_edges"] > 0
+
+
+def test_scenario_c_low_load_can_have_wrong_trajectory():
+    states = [evaluate(fixture("C", s)) for s in range(1, 4)]
+    assert len({s["ral"] for s in states}) == 1
+    assert states[-1]["ral"] < 40
+    assert states[-1]["trajectoryStability"] < states[0]["trajectoryStability"]
+    assert states[-1]["state"] == "WRONG TRAJECTORY"
+    assert states[-1]["expression"] == "wrong_trajectory"
+    assert "restart" in states[-1]["recommendedActions"]
+
+
+def test_scenario_d_summary_lowers_load_without_erasing_constraints():
+    store = Store()
+    before = store.submit(fixture("D"))
+    result = store.recover("summarize", before["state"]["observedAt"])
+    assert before["state"]["ral"] >= 75
+    assert result["state"]["ral"] < before["state"]["ral"]
+    assert result["state"]["deltaRal"] < 0
+    assert result["state"]["features"]["constraint"] == before["state"]["features"]["constraint"]
+    assert result["state"]["features"]["dependency_edges"] == before["state"]["features"]["dependency_edges"]
+    assert len(result["workingSet"]["items"]) == len(before["workingSet"]["items"])
+
+
+def test_scenario_e_restart_requires_fresh_validation_to_recover():
+    store = Store()
+    before = store.submit(fixture("E", 3))
+    handoff = store.recover("restart", before["state"]["observedAt"])
+    assert handoff["state"] == before["state"]  # Download is not a context restart.
+    fresh = fixture("E", 4)
+    fresh.observations = [o for o in fresh.observations if o.context != fresh.contextId]
+    unknown = store.submit(fresh)
+    assert unknown["state"]["trajectoryStability"] is None
+    recovered = store.submit(fixture("E", 5))
+    assert recovered["state"]["trajectoryStability"] > before["state"]["trajectoryStability"]
+    assert recovered["state"]["ral"] == before["state"]["ral"]
+
+
+def test_trend_uses_time_window_and_reports_feature_deltas():
+    store = Store()
+    a = store.submit(fixture("B", 1))
+    b = store.submit(fixture("B", 4))
+    assert b["state"]["deltaRal"] == b["state"]["ral"] - a["state"]["ral"]
+    assert b["state"]["trend"] == "rapid_rise"
+    assert {c["feature"] for c in b["state"]["changes"]} >= {"constraint", "dependency_edges"}
+    ws = fixture("B", 5)
+    ws.observedAt = 2000.0
+    assert store.submit(ws)["state"]["trend"] != "rapid_rise"
+
+
+def test_unknown_trajectory_does_not_override_load_and_task_switch_does_not_compare():
+    ws = fixture()
+    ws.observations = []
+    assert evaluate(ws)["state"] == "UNKNOWN"
+    assert evaluate(ws)["expression"] == "stable"
+    store = Store()
+    store.submit(ws)
+    assert store.submit(fixture("B"))["state"]["deltaRal"] is None
+
+
+@pytest.mark.parametrize("coverage", ["partial", "reviewed"])
+@pytest.mark.parametrize("step,expression", [(1,"stable"),(3,"loaded"),(5,"strained")])
+def test_structural_load_remains_visible_without_trajectory(coverage, step, expression):
+    ws = fixture("B", step)
+    ws.coverage = coverage
+    ws.observations = []
+    state = evaluate(ws)
+    assert state["trajectoryStability"] is None
+    assert state["state"] == "UNKNOWN"
+    assert state["expression"] == expression
+
+
+def test_fix_retains_relations_and_does_not_fake_lower_load():
+    store = Store()
+    before = store.submit(fixture("B", 3))
+    fixed = store.recover("fix", before["state"]["observedAt"])
+    assert fixed["state"]["ral"] == before["state"]["ral"]
+    assert all(i["fixed"] for i in fixed["workingSet"]["items"] if i["kind"] == "decision")
+
+
+def test_summary_preserves_history_referenced_by_active_items():
+    ws = fixture("D")
+    ws.dependencies.append(Edge(source="d0", target="h0-0", evidence="needed evidence"))
+    store = Store()
+    store.submit(ws)
+    result = store.recover("summarize", ws.observedAt)
+    assert next(i for i in result["workingSet"]["items"] if i["id"] == "h0-0")["status"] == "active"
+
+
+@pytest.mark.parametrize("action", ["split", "externalize", "resolve", "rebase", "restart"])
+def test_handoff_actions_do_not_claim_to_change_live_context(action):
+    store = Store()
+    before = store.submit(fixture())
+    result = store.recover(action, before["state"]["observedAt"])
+    assert result["recovery"]["effect"] == "handoff_created"
+    assert result["recovery"]["handoff"]["workingSet"] == before["workingSet"]
+    assert result["state"] == before["state"]
+
+
+@pytest.mark.parametrize("mutation", [
+    lambda d: d.update(unexpected="field"),
+    lambda d: d.update(observedAt=float("nan")),
+    lambda d: d.update(items=d["items"] * 2),
+    lambda d: d.update(dependencies=[{"source":"absent","target":"d0","evidence":"bad"}]),
+    lambda d: d["items"][0].update(depth=-1),
+    lambda d: d["items"][0].update(fixed="true"),
+])
+def test_invalid_boundary_data_is_rejected(mutation):
+    data = fixture().model_dump()
+    mutation(data)
+    with pytest.raises(ValidationError):
+        WorkingSet.model_validate(data)
+
+
+def test_timestamp_replay_and_stale_recovery():
+    store = Store()
+    ws = fixture()
+    first = store.submit(ws)
+    assert store.submit(ws) == first
+    stale = ws.model_copy(deep=True)
+    stale.observedAt = 1.0
+    with pytest.raises(ValueError, match="timestamps"):
+        store.submit(stale)
+    with pytest.raises(ValueError, match="refresh"):
+        store.recover("fix", 1.0)
+
+
+def test_extract_upserts_status_and_marks_unannotated_turn_partial():
+    data = scenario("A")["conversation"]
+    updated = dict(data["turns"][0]["items"][0], status="done")
+    data["turns"].append({"id":"update", "text":"Requirement complete", "items":[updated]})
+    ws = extract(Conversation.model_validate(data))
+    assert len(ws.items) == 5 and ws.items[0].status == "done"
+    data["turns"].append({"id":"unannotated", "text":"A new unknown requirement"})
+    assert extract(Conversation.model_validate(data)).coverage == "partial"
+    data["turns"][0]["items"][0]["source"] = "missing"
+    with pytest.raises(ValueError, match="supplied turn"):
+        extract(Conversation.model_validate(data))
+
+
+def test_persistence_restart_and_failed_write_do_not_mutate_state(tmp_path, monkeypatch):
+    from pathlib import Path
+    path = tmp_path / "session.json"
+    store = Store(path)
+    store.submit(fixture("B", 1))
+    before = store.submit(fixture("B", 2))
+    assert Store(path).view() == before
+    def fail(*args):
+        raise OSError("disk full")
+    monkeypatch.setattr(Path, "replace", fail)
+    with pytest.raises(OSError):
+        store.submit(fixture("B", 3))
+    assert store.view() == before
+
+
+def test_weights_validation():
+    with pytest.raises(ValueError):
+        Weights(working_set=-1)
+    with pytest.raises(ValueError):
+        Weights(working_set=float("nan"))
+
+
+def test_high_load_alone_never_recommends_restart():
+    state = evaluate(fixture("D"))
+    assert state["ral"] >= 75 and state["state"] == "HIGH LOAD"
+    assert "restart" not in state["recommendedActions"]
+
+
+@pytest.mark.parametrize("count,band", [(1,"stable"),(16,"loaded"),(24,"strained"),(30,"high_pressure"),(36,"unstable")])
+def test_five_visual_bands_and_critical_override(count, band):
+    ws = fixture()
+    ws.items = [Item(id=f"g-{i}", kind="goal", text="goal", source="test") for i in range(count)]
+    weights = Weights(working_set=100, dependency_complexity=0, constraint_density=0,
+                      decision_depth=0, conflict_pressure=0, context_dispersion=0)
+    assert evaluate(ws, weights=weights)["expression"] == band
+    ws.observations = fixture("C", 3).observations
+    result = evaluate(ws, weights=weights)
+    assert result["state"] == ("CRITICAL" if count >= 30 else "WRONG TRAJECTORY")
+
+
+def test_empty_partial_snapshot_stays_unknown_and_bounds_hold():
+    ws = WorkingSet(taskId="empty",contextId="c",observedAt=1.0,items=[])
+    result = evaluate(ws)
+    assert result["ral"] == 0 and result["trajectoryStability"] is None
+    assert result["state"] == "UNKNOWN"
+
+
+def test_http_api_auth_origin_validation_recovery_and_assets():
+    server, launch = make_server(Store())
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    base, token = launch.rstrip("/"), server.write_token
+    def request(path, data=None, auth=True, origin=None):
+        headers = {"Authorization":f"Bearer {token}"} if auth else {}
+        if origin:
+            headers["Origin"] = origin
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        req = Request(base + path, json.dumps(data).encode() if data is not None else None, headers)
+        with urlopen(req, timeout=5) as response:
+            return response.read()
+    try:
+        assert b"Attention Pet" in request("/", auth=False)
+        for path in ("/pet.js", "/pet.css"):
+            assert request(path, auth=False)
+        assert json.loads(request("/api/state", auth=False))["state"] is None
+        with pytest.raises(HTTPError) as error:
+            request("/api/snapshot", fixture().model_dump(), auth=False)
+        assert error.value.code == 401
+        with pytest.raises(HTTPError) as error:
+            request("/api/snapshot", fixture().model_dump(), origin="https://example.com")
+        assert error.value.code == 403
+        with pytest.raises(HTTPError) as error:
+            request("/api/snapshot", {"ral":99})
+        assert error.value.code == 400
+        before = json.loads(request("/api/conversation", scenario("D")["conversation"]))
+        after = json.loads(request("/api/recover", {"action":"summarize", "expectedObservedAt":before["state"]["observedAt"]}))
+        assert after["state"]["ral"] < before["state"]["ral"]
+        assert json.loads(request("/api/state"))["state"] == after["state"]
+        with pytest.raises(HTTPError) as error:
+            request("/api/demo", {"scenario":"C", "step":3})
+        assert error.value.code == 404
+        assert json.loads(request("/api/state"))["state"] == after["state"]
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)