Deploy GitHub main bbdacdb09d2a0c17d49fd8a49c8159317f3ec5b7

.env.example

@@ -0,0 +1,30 @@
+CUSTOMER_AI_DATA_ROOT=/data/customer-ai
+# Inbound signature used by the generic gateway destination when delivering to /internal/customer-ai/accept.
+CUSTOMER_AI_HMAC_SECRET=base64:replace_with_private_runtime_outbound_secret
+
+# Generic Webhook Gateway internal event API used for accepted/completed/recovery events.
+INTERNAL_EVENT_API_URL=https://webhooks.asterav8.jp/internal/events
+INTERNAL_EVENT_API_TOKEN=replace_with_long_random_internal_api_token
+INTERNAL_EVENT_SOURCE_ID=hf-private-runtime
+# Deployment-registered generic destination that returns events to the Cloudflare result receiver.
+INTERNAL_EVENT_RESULT_DESTINATION_ID=app-receiver
+INTERNAL_EVENT_API_TIMEOUT_SECONDS=10
+
+NOTION_TOKEN=
+NOTION_DATA_SOURCE_ID=2a2e5dd3-8492-45b9-a450-b362d02794b4
+CUSTOMER_AI_MODEL_ID=Qwen/Qwen3-4B-Instruct-2507
+CUSTOMER_AI_MODEL_REVISION=cdbee75f17c01a7cc42f958dc650907174af0554
+CUSTOMER_AI_ENABLE_MODEL=0
+CUSTOMER_AI_GPU_DAILY_BUDGET_SECONDS=2100
+CUSTOMER_AI_NODE_BINARY=node
+CUSTOMER_AI_NODE_SOCKET=/tmp/customer-ai-v8.sock
+CUSTOMER_AI_NODE_MEMORY_MB=384
+CUSTOMER_AI_JOB_LEASE_SECONDS=90
+CUSTOMER_AI_SESSION_LEASE_SECONDS=90
+CUSTOMER_AI_MAX_INPUT_CHARS=20000
+CUSTOMER_AI_PROCESS_CONCURRENCY=2
+CUSTOMER_AI_SESSION_CACHE_TTL_SECONDS=1800
+CUSTOMER_AI_SESSION_CACHE_MAX_SESSIONS=256
+CUSTOMER_AI_SESSION_CACHE_MAX_TURNS=12
+CUSTOMER_AI_KB_CACHE_TTL_SECONDS=120
+CUSTOMER_AI_KB_CACHE_MAX_ENTRIES=256

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+.pytest_cache/
+.coverage
+htmlcov/
+.venv/
+.env
+*.pyc
+*.pyo
+*.sqlite
+*.sqlite-shm
+*.sqlite-wal
+node_modules/
+/data/
+.runtime/

README.md

@@ -1,13 +1,170 @@
 ---
-title: Astera CustomerAI
-emoji: 😻
-colorFrom: pink
+title: Astera Customer AI
+emoji: ✨
+colorFrom: gray
 colorTo: yellow
 sdk: gradio
-sdk_version: 6.20.0
-python_version: '3.13'
+sdk_version: 6.5.1
 app_file: app.py
 pinned: false
+license: other
+short_description: Private Astera-derived customer-response runtime
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Astera Customer AI
+
+Private Hugging Face Space runtime for answering questions about Astera and the owner's development products.
+
+## Fixed purpose
+
+This is not a generic AI, multi-AI coordinator, FAQ wall, or standalone lightweight-model agent.
+
+It is a specialized response system that must:
+
+- understand Japanese first questions and follow-up questions;
+- preserve the user's goal, active topic, confirmed details, answered questions, and unresolved questions;
+- decompose documents and multi-question messages into explicit tasks;
+- search the approved KB for each task;
+- bind evidence to the task it answers;
+- construct an answer blueprint before any model call;
+- use a lightweight model only when natural composition is necessary;
+- verify coverage, evidence, topic, unsafe claims, and private information;
+- allow at most one violation-targeted repair;
+- create anonymized, deduplicated, review-only KB feedback candidates.
+
+Astera itself is not executed. The runtime adapts the useful Astera/KAGRRA engineering logic for document analysis, task decomposition, search planning, evidence organization, answer integration, bounded state, and output verification.
+
+## Processing path
+
+```text
+Current message
+  -> normalize
+  -> bounded session context
+  -> document/question decomposition
+  -> task classification
+  -> per-task KB search planning
+  -> Notion retrieval
+  -> evidence binding
+  -> answer blueprint
+  -> deterministic answer or optional model composition
+  -> deterministic verification
+  -> one bounded repair
+  -> generic Webhook Gateway reply event
+  -> app/HP receiver
+```
+
+## Runtime topology
+
+```text
+Cloudflare Customer AI Edge
+  -> Universal Webhook Gateway generic POST /internal/events
+  -> Private Hugging Face Space
+  -> Private Hugging Face Bucket mounted at /data/customer-ai
+  -> Notion KB
+  -> Universal Webhook Gateway generic POST /internal/events
+  -> Cloudflare receiver
+```
+
+The browser must not call this private Space directly.
+
+## Generic internal event contract
+
+Ingress event:
+
+- `event_type`: `customer_ai.requested`
+- `source_id`: Cloudflare source identity
+- `destination_ids`: includes the HF private-runtime destination
+- `payload`: normalized customer message, locale, channel, session ID, and optional document
+
+Result event:
+
+- `event_type`: `customer_ai.completed`
+- `source_id`: `hf-private-runtime`
+- `destination_ids`: includes the app receiver
+- `payload`: answer, citations, verification report, session state summary, and deduplicated feedback candidate references
+
+No Customer-AI-specific route is added to the universal Gateway.
+
+## Runtime endpoints
+
+- `GET /healthz`
+- `GET /readyz`
+- `POST /internal/events`
+- `POST /internal/customer-ai`
+
+The direct customer endpoint exists for private runtime verification and controlled internal callers. The production integration uses the generic event endpoint.
+
+## Authentication
+
+The Space verifies the same generic Gateway HMAC headers used by the repository adapter:
+
+- `X-Webhook-Timestamp`
+- `X-Webhook-Nonce`
+- `X-Webhook-Signature`
+
+The signing secret is injected as `CUSTOMER_AI_HMAC_SECRET`.
+
+## Runtime persistence
+
+All writable runtime state lives under `CUSTOMER_AI_DATA_ROOT`.
+
+The deployment provisions a private HF Bucket named `G-ACE/astera-customerai-data` and mounts it at:
+
+```text
+/data/customer-ai
+```
+
+Persisted files include:
+
+- session state;
+- KB search cache;
+- feedback candidates;
+- feedback deduplication index;
+- owner-review feedback JSONL.
+
+## Optional model
+
+The default runtime mode is `CUSTOMER_AI_ENABLE_MODEL=0`.
+
+The deterministic path remains operational without loading a model. When enabled, the model is pinned to:
+
+```text
+Qwen/Qwen3-4B-Instruct-2507
+revision: cdbee75f17c01a7cc42f958dc650907174af0554
+```
+
+The model may compose language from the answer blueprint. It does not own task decomposition, KB retrieval, evidence binding, verification, or feedback approval.
+
+## Important environment variables
+
+| Name | Purpose |
+|---|---|
+| `CUSTOMER_AI_HMAC_SECRET` | Generic Gateway request authentication |
+| `CUSTOMER_AI_DATA_ROOT` | Mounted persistent data root |
+| `NOTION_TOKEN` | Approved KB access |
+| `NOTION_DATA_SOURCE_ID` | Approved KB data source |
+| `INTERNAL_EVENT_API_URL` | Generic Gateway internal event endpoint |
+| `INTERNAL_EVENT_API_TOKEN` | Gateway internal bearer token |
+| `CUSTOMER_AI_ENABLE_MODEL` | Enables optional lightweight model |
+| `CUSTOMER_AI_MODEL_ID` | Pinned model ID |
+| `CUSTOMER_AI_MODEL_REVISION` | Pinned model revision |
+| `CUSTOMER_AI_GPU_DAILY_BUDGET_SECONDS` | Internal daily GPU budget guard |
+| `INTERNAL_EVENT_SOURCE_ID` | Source ID for result events |
+| `INTERNAL_EVENT_RESULT_DESTINATION_ID` | Result receiver destination ID |
+
+## Deployment
+
+The deployment workflow:
+
+1. checks out `main`;
+2. runs the complete repository verification suite;
+3. creates or reuses the private Bucket;
+4. creates or reuses the private Space;
+5. attaches the Bucket at `/data/customer-ai`;
+6. configures Space secrets and variables;
+7. uploads the current `main` source;
+8. restarts the Space;
+9. verifies Bucket write/read/delete;
+10. waits for authenticated `/healthz` and `/readyz` responses.
+
+The deployment uses the registered Hugging Face access secret from GitHub Actions and never places GitHub in the production request path.

app.py

@@ -0,0 +1,155 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from contextlib import asynccontextmanager
+
+import gradio as gr
+import uvicorn
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+
+from runtime import CustomerAIService
+from runtime.schemas import CloudEvent
+from runtime.security import verify_hmac, verify_standard_webhook
+from runtime.storage import ConflictError, NotFoundError
+
+MAX_INTERNAL_BODY_BYTES = 10 * 1024 * 1024
+
+logging.basicConfig(level=logging.INFO)
+service = CustomerAIService()
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    await service.startup()
+    yield
+    await service.shutdown()
+
+
+api = FastAPI(title="Astera Customer AI", version="1.1.0", lifespan=lifespan, docs_url=None, redoc_url=None)
+
+
+@api.get("/healthz")
+async def healthz() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+@api.get("/readyz")
+async def readyz() -> JSONResponse:
+    checks = service.readiness()
+    ready = checks["data_root"] and checks["v8"]
+    return JSONResponse(status_code=200 if ready else 503, content={"ready": ready, "checks": checks})
+
+
+@api.post("/internal/customer-ai/accept")
+async def accept(request: Request) -> JSONResponse:
+    if request.headers.get("content-type", "").split(";", 1)[0] not in {"application/json", "application/cloudevents+json"}:
+        raise HTTPException(status_code=415, detail="unsupported_content_type")
+    declared = int(request.headers.get("content-length", "0") or 0)
+    if declared > service.settings.max_input_chars * 4:
+        raise HTTPException(status_code=413, detail="payload_too_large")
+    raw = await request.body()
+    if len(raw) > service.settings.max_input_chars * 4:
+        raise HTTPException(status_code=413, detail="payload_too_large")
+    webhook_id = request.headers.get("webhook-id", "")
+    timestamp = request.headers.get("webhook-timestamp", "")
+    signature = request.headers.get("webhook-signature", "")
+    if not verify_standard_webhook(
+        raw,
+        webhook_id,
+        timestamp,
+        signature,
+        service.settings.hmac_secret,
+    ):
+        raise HTTPException(status_code=401, detail="invalid_standard_webhook_signature")
+    try:
+        event = CloudEvent.model_validate_json(raw)
+        record, created = await service.accept(event)
+    except ConflictError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except (ValueError, KeyError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return JSONResponse(status_code=202, content={"accepted": True, "created": created, "job": record})
+
+
+@api.get("/internal/customer-ai/jobs/{job_id}")
+async def job_status(job_id: str) -> dict:
+    try:
+        record = service.jobs.get_job(job_id)
+    except NotFoundError as exc:
+        raise HTTPException(status_code=404, detail="job_not_found") from exc
+    result = service.jobs.get_result(job_id)
+    return {"job": record.model_dump(mode="json"), "result": result}
+
+
+@api.post("/internal/kb/sync")
+async def kb_sync(request: Request) -> JSONResponse:
+    declared = int(request.headers.get("content-length", "0") or 0)
+    if declared > MAX_INTERNAL_BODY_BYTES:
+        raise HTTPException(status_code=413, detail="payload_too_large")
+    raw = await request.body()
+    if len(raw) > MAX_INTERNAL_BODY_BYTES:
+        raise HTTPException(status_code=413, detail="payload_too_large")
+    if not verify_hmac(
+        raw,
+        request.headers.get("x-webhook-timestamp", ""),
+        request.headers.get("x-webhook-signature", ""),
+        service.settings.hmac_secret,
+    ):
+        raise HTTPException(status_code=401, detail="invalid_signature")
+    payload = json.loads(raw)
+    pages = payload.get("pages")
+    version = str(payload.get("version", ""))
+    if not version:
+        raise HTTPException(status_code=422, detail="version_required")
+    if pages is None:
+        result = await service.sync_notion_kb(version)
+    elif isinstance(pages, list):
+        info = await asyncio.to_thread(service.kb.build_snapshot, version=version, pages=pages)
+        service.kb.open()
+        result = {"version": info.version, "path": str(info.path), "source_pages": len(pages)}
+    else:
+        raise HTTPException(status_code=422, detail="pages_must_be_list")
+    return JSONResponse(status_code=202, content=result)
+
+
+@api.post("/internal/recovery/run")
+async def recovery(request: Request) -> dict:
+    raw = await request.body()
+    if not verify_hmac(
+        raw,
+        request.headers.get("x-webhook-timestamp", ""),
+        request.headers.get("x-webhook-signature", ""),
+        service.settings.hmac_secret,
+    ):
+        raise HTTPException(status_code=401, detail="invalid_signature")
+    result = await service.recover_once()
+    return {"accepted": True, **result}
+
+
+async def process_job(job_id: str) -> dict:
+    return await service.process_job(job_id)
+
+
+with gr.Blocks(title="Astera Customer AI") as demo:
+    gr.Markdown("# Astera Customer AI\nPrivate runtime. Use the Astera HP or app.")
+    job_id = gr.Textbox(label="Job ID", visible=False)
+    output = gr.JSON(visible=False)
+    trigger = gr.Button("Process", visible=False)
+    trigger.click(
+        fn=process_job,
+        inputs=job_id,
+        outputs=output,
+        api_name="customer_ai_process",
+        api_description="Process one durably accepted Customer AI job by ID.",
+        queue=True,
+        concurrency_limit=2,
+        api_visibility="private",
+    )
+
+app = gr.mount_gradio_app(api, demo, path="/")
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=7860, log_level="info")

package.json

@@ -0,0 +1,12 @@
+{
+  "name": "astera-customer-ai-v8-runtime",
+  "version": "1.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {"node": ">=22.0.0"},
+  "scripts": {
+    "test": "node --test v8/test/*.test.mjs",
+    "test:edge": "node --test edge/test/*.test.mjs",
+    "check:edge": "node --check edge/src/worker.js"
+  }
+}

packages.txt

@@ -0,0 +1,3 @@
+git
+xz-utils
+ca-certificates

pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "astera-customer-ai"
+version = "1.1.0"
+requires-python = ">=3.11"
+
+[tool.pytest.ini_options]
+addopts = "-q --strict-markers"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "SIM"]
+ignore = ["E501"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_unused_configs = true
+check_untyped_defs = true
+no_implicit_optional = true

requirements-dev.txt

@@ -0,0 +1,5 @@
+-r requirements.txt
+pytest==9.0.2
+pytest-asyncio>=1.0,<2
+ruff>=0.12,<1
+mypy>=1.17,<2

requirements.txt

@@ -0,0 +1,10 @@
+gradio==6.5.1
+fastapi==0.128.2
+pydantic==2.13.4
+uvicorn==0.48.0
+httpx>=0.28,<1
+huggingface_hub==1.16.1
+spaces>=0.41,<1
+transformers>=4.57,<6
+safetensors>=0.5,<1
+torch>=2.8,<3

runtime/__init__.py

@@ -0,0 +1,3 @@
+from .service import CustomerAIService
+
+__all__ = ["CustomerAIService"]

runtime/config.py

@@ -0,0 +1,78 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def _int(name: str, default: int) -> int:
+    value = int(os.getenv(name, str(default)))
+    if value <= 0:
+        raise ValueError(f"{name} must be positive")
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    data_root: Path
+    hmac_secret: str
+    internal_event_api_url: str
+    internal_event_api_token: str
+    internal_event_source_id: str
+    internal_event_result_destination_id: str
+    notion_token: str
+    notion_data_source_id: str
+    model_id: str
+    model_revision: str
+    enable_model: bool
+    gpu_daily_budget_seconds: int
+    node_binary: str
+    node_socket: Path
+    node_memory_mb: int
+    job_lease_seconds: int
+    session_lease_seconds: int
+    max_input_chars: int
+    process_concurrency: int
+    internal_event_api_timeout_seconds: int
+    session_cache_ttl_seconds: int
+    session_cache_max_sessions: int
+    session_cache_max_turns: int
+    kb_cache_ttl_seconds: int
+    kb_cache_max_entries: int
+
+    @classmethod
+    def load(cls) -> "Settings":
+        root = Path(os.getenv("CUSTOMER_AI_DATA_ROOT", "/data/customer-ai")).resolve()
+        return cls(
+            data_root=root,
+            hmac_secret=os.getenv("CUSTOMER_AI_HMAC_SECRET", ""),
+            internal_event_api_url=os.getenv("INTERNAL_EVENT_API_URL", ""),
+            internal_event_api_token=os.getenv("INTERNAL_EVENT_API_TOKEN", ""),
+            internal_event_source_id=os.getenv("INTERNAL_EVENT_SOURCE_ID", "hf-private-runtime"),
+            internal_event_result_destination_id=os.getenv(
+                "INTERNAL_EVENT_RESULT_DESTINATION_ID", ""
+            ),
+            notion_token=os.getenv("NOTION_TOKEN", ""),
+            notion_data_source_id=os.getenv("NOTION_DATA_SOURCE_ID", ""),
+            model_id=os.getenv("CUSTOMER_AI_MODEL_ID", "Qwen/Qwen3-4B-Instruct-2507"),
+            model_revision=os.getenv("CUSTOMER_AI_MODEL_REVISION", ""),
+            enable_model=os.getenv("CUSTOMER_AI_ENABLE_MODEL", "0") == "1",
+            gpu_daily_budget_seconds=_int("CUSTOMER_AI_GPU_DAILY_BUDGET_SECONDS", 2100),
+            node_binary=os.getenv("CUSTOMER_AI_NODE_BINARY", "node"),
+            node_socket=Path(os.getenv("CUSTOMER_AI_NODE_SOCKET", "/tmp/customer-ai-v8.sock")),
+            node_memory_mb=_int("CUSTOMER_AI_NODE_MEMORY_MB", 384),
+            job_lease_seconds=_int("CUSTOMER_AI_JOB_LEASE_SECONDS", 90),
+            session_lease_seconds=_int("CUSTOMER_AI_SESSION_LEASE_SECONDS", 90),
+            max_input_chars=_int("CUSTOMER_AI_MAX_INPUT_CHARS", 20000),
+            process_concurrency=_int("CUSTOMER_AI_PROCESS_CONCURRENCY", 2),
+            internal_event_api_timeout_seconds=_int("INTERNAL_EVENT_API_TIMEOUT_SECONDS", 10),
+            session_cache_ttl_seconds=_int("CUSTOMER_AI_SESSION_CACHE_TTL_SECONDS", 1800),
+            session_cache_max_sessions=_int("CUSTOMER_AI_SESSION_CACHE_MAX_SESSIONS", 256),
+            session_cache_max_turns=_int("CUSTOMER_AI_SESSION_CACHE_MAX_TURNS", 12),
+            kb_cache_ttl_seconds=_int("CUSTOMER_AI_KB_CACHE_TTL_SECONDS", 120),
+            kb_cache_max_entries=_int("CUSTOMER_AI_KB_CACHE_MAX_ENTRIES", 256),
+        )
+
+    def ensure_directories(self) -> None:
+        for name in ("jobs", "sessions", "kb/snapshots", "runtime", "temporary"):
+            (self.data_root / name).mkdir(parents=True, exist_ok=True)

runtime/control.py

@@ -0,0 +1,412 @@
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from .conversation import ConversationCache
+from .schemas import SessionContext
+from .security import contains_internal_implementation, redact_text
+from .support import FeedbackStore, PreparedSupport, SupportRuntime, validate_response
+from .v8 import V8Unavailable
+
+
+@dataclass(slots=True)
+class ConversationOutcome:
+    status: str
+    answer: str
+    kb_ids: list[str]
+    facts: list[str]
+    engine_invoked: bool
+    clarification: str | None
+    context_used: bool
+    analysis: dict[str, Any]
+    violations: list[str]
+    processing_grade: str
+    question_tasks: list[dict[str, Any]]
+    blueprint: dict[str, Any]
+    repair_attempted: bool
+    feedback_candidate_id: str | None
+    execution: dict[str, Any]
+
+
+class ConversationCore:
+    """Astera-derived support pipeline specialized for Customer AI response handling."""
+
+    def __init__(
+        self,
+        *,
+        v8: Any,
+        engine: Any,
+        cache: ConversationCache,
+        search: Callable[..., list[Any]],
+        feedback_store: FeedbackStore | None = None,
+    ) -> None:
+        self.v8 = v8
+        self.engine = engine
+        self.cache = cache
+        self.search = search
+        self.support = SupportRuntime(search=search)
+        self.feedback_store = feedback_store
+
+    async def execute(self, *, request: Any) -> ConversationOutcome:
+        context = self.cache.get(request.session_id)
+        compact_context = self.cache.compact(context)
+        analysis = await self._analyze(request.message, compact_context, request.source)
+        prepared = await self.support.prepare(
+            message=request.message,
+            locale=request.locale,
+            source=request.source,
+            context=compact_context,
+            analysis=analysis,
+        )
+
+        answer, answered_task_ids, unresolved_task_ids, used_evidence_ids = self._deterministic_state(prepared)
+        returned_goal = str(analysis.get("user_goal") or context.user_goal or request.message).strip()
+        returned_topic = str(analysis.get("active_topic") or context.active_topic or "general").strip()
+        engine_invoked = False
+        repair_attempted = False
+        first_attempt_violations: list[str] = []
+
+        packet = self._engine_packet(
+            request=request,
+            compact_context=compact_context,
+            prepared=prepared,
+            analysis=analysis,
+        )
+        if prepared.model_required and prepared.evidence and self.engine.available():
+            generated = await self._execute_engine(packet)
+            if generated is not None:
+                answer, returned_goal, returned_topic, answered_task_ids, unresolved_task_ids, used_evidence_ids = self._apply_engine_output(
+                    generated=generated,
+                    fallback_answer=answer,
+                    returned_goal=returned_goal,
+                    returned_topic=returned_topic,
+                    default_answered=answered_task_ids,
+                    default_unresolved=unresolved_task_ids,
+                    default_evidence=used_evidence_ids,
+                )
+                engine_invoked = True
+
+        verification = await self._verify_response(
+            answer=answer,
+            analysis=analysis,
+            prepared=prepared,
+            returned_topic=returned_topic,
+            answered_task_ids=answered_task_ids,
+            unresolved_task_ids=unresolved_task_ids,
+            used_evidence_ids=used_evidence_ids,
+        )
+        validation = validate_response(
+            answer=answer,
+            prepared=prepared,
+            answered_task_ids=answered_task_ids,
+            unresolved_task_ids=unresolved_task_ids,
+            used_evidence_ids=used_evidence_ids,
+            external_violations=verification.get("violations") or [],
+        )
+
+        if not validation.passed and engine_invoked:
+            first_attempt_violations = list(validation.violations)
+            repair_attempted = True
+            repair_packet = {
+                **packet,
+                "repair": {
+                    "attempt": 1,
+                    "previous_answer": answer[:12000],
+                    "violations": validation.violations,
+                    "required_answered_task_ids": [item.task_id for item in prepared.tasks if item.task_id not in prepared.blueprint.get("unresolved_task_ids", [])],
+                    "required_unresolved_task_ids": list(prepared.blueprint.get("unresolved_task_ids", [])),
+                    "allowed_evidence_ids": [item.evidence_id for item in prepared.evidence],
+                },
+            }
+            repaired = await self._execute_engine(repair_packet)
+            if repaired is not None:
+                answer, returned_goal, returned_topic, answered_task_ids, unresolved_task_ids, used_evidence_ids = self._apply_engine_output(
+                    generated=repaired,
+                    fallback_answer=prepared.blueprint["deterministic_answer"],
+                    returned_goal=returned_goal,
+                    returned_topic=returned_topic,
+                    default_answered=[section["task_id"] for section in prepared.blueprint["sections"] if section["resolved"]],
+                    default_unresolved=list(prepared.blueprint.get("unresolved_task_ids", [])),
+                    default_evidence=list(prepared.blueprint.get("evidence_ids", [])),
+                )
+            verification = await self._verify_response(
+                answer=answer,
+                analysis=analysis,
+                prepared=prepared,
+                returned_topic=returned_topic,
+                answered_task_ids=answered_task_ids,
+                unresolved_task_ids=unresolved_task_ids,
+                used_evidence_ids=used_evidence_ids,
+            )
+            validation = validate_response(
+                answer=answer,
+                prepared=prepared,
+                answered_task_ids=answered_task_ids,
+                unresolved_task_ids=unresolved_task_ids,
+                used_evidence_ids=used_evidence_ids,
+                external_violations=verification.get("violations") or [],
+            )
+
+        if not validation.passed:
+            answer, answered_task_ids, unresolved_task_ids, used_evidence_ids = self._deterministic_state(prepared)
+            verification = await self._verify_response(
+                answer=answer,
+                analysis=analysis,
+                prepared=prepared,
+                returned_topic=str(analysis.get("active_topic") or returned_topic),
+                answered_task_ids=answered_task_ids,
+                unresolved_task_ids=unresolved_task_ids,
+                used_evidence_ids=used_evidence_ids,
+            )
+            validation = validate_response(
+                answer=answer,
+                prepared=prepared,
+                answered_task_ids=answered_task_ids,
+                unresolved_task_ids=unresolved_task_ids,
+                used_evidence_ids=used_evidence_ids,
+                external_violations=verification.get("violations") or [],
+            )
+            returned_topic = str(analysis.get("active_topic") or returned_topic)
+            engine_invoked = False
+
+        answer = redact_text(answer).text.strip()
+        if contains_internal_implementation(answer):
+            answer = (
+                "内部実装の非公開部分ではなく、利用方法、仕様、問題解決に必要な範囲で具体的に説明します。"
+                if request.locale == "ja-JP"
+                else "I can explain supported use, specifications, and resolution steps without exposing private implementation details."
+            )
+            validation.violations.append("internal_implementation")
+            unresolved_task_ids = list(dict.fromkeys([*unresolved_task_ids, *[item.task_id for item in prepared.tasks]]))
+            answered_task_ids = []
+
+        clarification = self._clarification(prepared, unresolved_task_ids)
+        status = "awaiting_clarification" if unresolved_task_ids else "completed"
+        question_ledger = self._updated_ledger(context, request.message_id, prepared, answered_task_ids, unresolved_task_ids)
+        evidence_cache = self._updated_evidence_cache(context, prepared)
+        answered_ledger_ids = [
+            f"{request.message_id}:{task_id}" for task_id in answered_task_ids
+        ]
+        updated = SessionContext(
+            session_id=request.session_id,
+            user_goal=returned_goal[:1000],
+            active_topic=returned_topic[:160],
+            confirmed_details=dict(analysis.get("confirmed_details") or context.confirmed_details),
+            unresolved_questions=[
+                item.text for item in prepared.tasks if item.task_id in unresolved_task_ids
+            ],
+            last_kb_ids=[item.kb_id for item in prepared.evidence],
+            turns=context.turns,
+            answered_question_ids=list(dict.fromkeys([*context.answered_question_ids, *answered_ledger_ids])),
+            question_ledger=question_ledger,
+            evidence_cache=evidence_cache,
+            last_blueprint=prepared.blueprint,
+        )
+        updated = self.cache.append_turns(
+            updated,
+            user_text=request.message,
+            assistant_text=answer,
+            message_id=request.message_id,
+            kb_ids=[item.kb_id for item in prepared.evidence],
+        )
+        self.cache.save(updated)
+
+        candidate_id = None
+        if self.feedback_store is not None:
+            candidate_id = self.feedback_store.record(
+                session_id=request.session_id,
+                message=request.message,
+                prepared=prepared,
+                validation=validation,
+                status=status,
+            )
+
+        final_violations = list(dict.fromkeys(validation.violations))
+        execution = {
+            "pipeline": "astera-derived-document-task-search-evidence-blueprint",
+            "processing_grade": prepared.processing_grade,
+            "question_count": len(prepared.tasks),
+            "search_task_count": len(prepared.search_tasks),
+            "evidence_count": len(prepared.evidence),
+            "engine_required": prepared.model_required,
+            "engine_invoked": engine_invoked,
+            "repair_attempted": repair_attempted,
+            "repair_limit": 1,
+            "first_attempt_violations": first_attempt_violations,
+            "answered_task_ids": answered_task_ids,
+            "unresolved_task_ids": unresolved_task_ids,
+            "used_evidence_ids": used_evidence_ids,
+            "feedback_candidate_id": candidate_id,
+        }
+        return ConversationOutcome(
+            status=status,
+            answer=answer,
+            kb_ids=[item.kb_id for item in prepared.evidence],
+            facts=[item.short_answer for item in prepared.evidence],
+            engine_invoked=engine_invoked,
+            clarification=clarification,
+            context_used=bool(analysis.get("context_used")),
+            analysis=analysis | {"analysis_dictionary": prepared.analysis_dictionary},
+            violations=final_violations,
+            processing_grade=prepared.processing_grade,
+            question_tasks=[item.as_dict() for item in prepared.tasks],
+            blueprint=prepared.blueprint,
+            repair_attempted=repair_attempted,
+            feedback_candidate_id=candidate_id,
+            execution=execution,
+        )
+
+    async def _analyze(self, message: str, context: dict[str, Any], source: str) -> dict[str, Any]:
+        try:
+            return await self.v8.request("analyze_turn", {"message": message, "context": context, "source": source})
+        except V8Unavailable:
+            active_topic = str(context.get("active_topic") or "general")
+            goal = str(context.get("user_goal") or message)
+            query = " ".join(item for item in (message, goal, active_topic) if item and item != "general")
+            return {
+                "message": message,
+                "follow_up": bool(context.get("user_goal")),
+                "context_used": bool(context.get("user_goal") or context.get("turns")),
+                "active_topic": active_topic,
+                "user_goal": goal,
+                "confirmed_details": dict(context.get("confirmed_details") or {}),
+                "retrieval_query": query,
+            }
+
+    async def _execute_engine(self, packet: dict[str, Any]) -> dict[str, Any] | None:
+        try:
+            return await asyncio.to_thread(self.engine.execute, packet)
+        except Exception:
+            return None
+
+    async def _verify_response(
+        self,
+        *,
+        answer: str,
+        analysis: dict[str, Any],
+        prepared: PreparedSupport,
+        returned_topic: str,
+        answered_task_ids: list[str],
+        unresolved_task_ids: list[str],
+        used_evidence_ids: list[str],
+    ) -> dict[str, Any]:
+        payload = {
+            "answer": answer,
+            "analysis": analysis,
+            "returned_topic": returned_topic,
+            "question_task_ids": [item.task_id for item in prepared.tasks],
+            "answered_task_ids": answered_task_ids,
+            "unresolved_task_ids": unresolved_task_ids,
+            "used_evidence_ids": used_evidence_ids,
+            "available_evidence_ids": [item.evidence_id for item in prepared.evidence],
+        }
+        try:
+            return await self.v8.request("verify_turn", payload)
+        except V8Unavailable:
+            return {"answer": answer, "passed": bool(answer.strip()), "violations": [] if answer.strip() else ["empty_answer"]}
+
+    @staticmethod
+    def _engine_packet(
+        *,
+        request: Any,
+        compact_context: dict[str, Any],
+        prepared: PreparedSupport,
+        analysis: dict[str, Any],
+    ) -> dict[str, Any]:
+        return {
+            "message": prepared.normalized_message[:8000],
+            "conversation": compact_context,
+            "support_packet": prepared.as_packet(),
+            "analysis": analysis,
+            "response_rules": {
+                "answer_only_from_supplied_evidence": True,
+                "answer_each_question_task": True,
+                "preserve_user_goal_and_topic": True,
+                "do_not_repeat_answered_questions": True,
+                "ask_only_for_specific_missing_information": True,
+                "do_not_claim_unexecuted_actions": True,
+                "do_not_expose_private_implementation": True,
+                "locale": request.locale,
+            },
+        }
+
+    @staticmethod
+    def _apply_engine_output(
+        *,
+        generated: dict[str, Any],
+        fallback_answer: str,
+        returned_goal: str,
+        returned_topic: str,
+        default_answered: list[str],
+        default_unresolved: list[str],
+        default_evidence: list[str],
+    ) -> tuple[str, str, str, list[str], list[str], list[str]]:
+        answer = str(generated.get("answer") or fallback_answer).strip()
+        goal = str(generated.get("user_goal") or returned_goal).strip()
+        topic = str(generated.get("active_topic") or returned_topic).strip()
+        answered = [str(item) for item in generated.get("answered_task_ids", default_answered) if str(item)]
+        unresolved = [str(item) for item in generated.get("unresolved_task_ids", default_unresolved) if str(item)]
+        evidence = [str(item) for item in generated.get("used_evidence_ids", default_evidence) if str(item)]
+        return answer, goal, topic, answered, unresolved, evidence
+
+    @staticmethod
+    def _deterministic_state(prepared: PreparedSupport) -> tuple[str, list[str], list[str], list[str]]:
+        answered = [section["task_id"] for section in prepared.blueprint["sections"] if section["resolved"]]
+        unresolved = list(prepared.blueprint.get("unresolved_task_ids", []))
+        return (
+            str(prepared.blueprint.get("deterministic_answer") or "").strip(),
+            answered,
+            unresolved,
+            list(prepared.blueprint.get("evidence_ids", [])),
+        )
+
+    @staticmethod
+    def _clarification(prepared: PreparedSupport, unresolved_task_ids: list[str]) -> str | None:
+        if not unresolved_task_ids:
+            return None
+        sections = [
+            section["body"]
+            for section in prepared.blueprint.get("sections", [])
+            if section.get("task_id") in unresolved_task_ids and section.get("body")
+        ]
+        return "\n\n".join(dict.fromkeys(sections)) or None
+
+    @staticmethod
+    def _updated_ledger(
+        context: SessionContext,
+        message_id: str,
+        prepared: PreparedSupport,
+        answered_task_ids: list[str],
+        unresolved_task_ids: list[str],
+    ) -> list[dict[str, Any]]:
+        new_rows = []
+        for task in prepared.tasks:
+            new_rows.append(
+                {
+                    "ledger_id": f"{message_id}:{task.task_id}",
+                    "message_id": message_id,
+                    "task": task.as_dict(),
+                    "status": "answered" if task.task_id in answered_task_ids else "unresolved" if task.task_id in unresolved_task_ids else "pending",
+                    "evidence_ids": [item.evidence_id for item in prepared.evidence if task.task_id in item.task_ids],
+                }
+            )
+        return [*context.question_ledger, *new_rows][-24:]
+
+    @staticmethod
+    def _updated_evidence_cache(context: SessionContext, prepared: PreparedSupport) -> dict[str, dict[str, Any]]:
+        cache = dict(context.evidence_cache)
+        for item in prepared.evidence:
+            cache[item.evidence_id] = {
+                "kb_id": item.kb_id,
+                "question": item.question[:600],
+                "short_answer": item.short_answer[:1200],
+                "answer_boundary": item.answer_boundary[:600],
+                "task_ids": item.task_ids,
+            }
+        return dict(list(cache.items())[-16:])
+
+
+ControlledExecutionCore = ConversationCore
+ControlOutcome = ConversationOutcome

runtime/conversation.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import copy
+import time
+from collections import OrderedDict
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from .schemas import ConversationTurn, SessionContext
+from .storage import AtomicStore
+
+
+class ConversationCache:
+    """Bounded in-memory LRU backed by one persistent session context file."""
+
+    def __init__(self, root: Path, *, ttl_seconds: int, max_sessions: int, max_turns: int):
+        self.root = root / "sessions"
+        self.store = AtomicStore(root)
+        self.ttl_seconds = ttl_seconds
+        self.max_sessions = max_sessions
+        self.max_turns = max_turns
+        self._memory: OrderedDict[str, tuple[float, SessionContext]] = OrderedDict()
+
+    def get(self, session_id: str) -> SessionContext:
+        now = time.monotonic()
+        cached = self._memory.get(session_id)
+        if cached and cached[0] > now:
+            self._memory.move_to_end(session_id)
+            return SessionContext.model_validate(copy.deepcopy(cached[1].model_dump(mode="json")))
+        if cached:
+            self._memory.pop(session_id, None)
+
+        path = self._path(session_id)
+        if path.exists():
+            context = SessionContext.model_validate(self.store.get_json(path))
+        else:
+            context = SessionContext(session_id=session_id)
+        self._remember(context)
+        return SessionContext.model_validate(copy.deepcopy(context.model_dump(mode="json")))
+
+    def save(self, context: SessionContext) -> None:
+        evidence_items = list(context.evidence_cache.items())[-16:]
+        trimmed = context.model_copy(
+            update={
+                "turns": context.turns[-self.max_turns :],
+                "unresolved_questions": context.unresolved_questions[-16:],
+                "last_kb_ids": context.last_kb_ids[-16:],
+                "answered_question_ids": context.answered_question_ids[-32:],
+                "question_ledger": context.question_ledger[-24:],
+                "evidence_cache": dict(evidence_items),
+                "last_blueprint": _bound_structure(context.last_blueprint, max_chars=16000),
+                "updated_at": datetime.now(UTC),
+            }
+        )
+        self.store.put_json(self._path(trimmed.session_id), trimmed.model_dump(mode="json"))
+        self._remember(trimmed)
+
+    def append_turns(
+        self,
+        context: SessionContext,
+        *,
+        user_text: str,
+        assistant_text: str,
+        message_id: str,
+        kb_ids: list[str],
+    ) -> SessionContext:
+        turns = [
+            *context.turns,
+            ConversationTurn(role="user", text=user_text[:8000], message_id=message_id),
+            ConversationTurn(role="assistant", text=assistant_text[:8000], message_id=message_id, kb_ids=kb_ids),
+        ]
+        return context.model_copy(update={"turns": turns[-self.max_turns :]})
+
+    def compact(self, context: SessionContext, *, last_turns: int = 6) -> dict[str, Any]:
+        turns = []
+        for turn in context.turns[-last_turns:]:
+            turns.append(
+                {
+                    "role": turn.role,
+                    "text": turn.text[:1200],
+                    "message_id": turn.message_id,
+                    "kb_ids": turn.kb_ids[-4:],
+                }
+            )
+        evidence = {
+            key: _bound_structure(value, max_chars=1600)
+            for key, value in list(context.evidence_cache.items())[-8:]
+        }
+        return {
+            "user_goal": context.user_goal[:1000],
+            "active_topic": context.active_topic[:160],
+            "confirmed_details": _bound_structure(context.confirmed_details, max_chars=4000),
+            "unresolved_questions": [item[:500] for item in context.unresolved_questions[-8:]],
+            "last_kb_ids": context.last_kb_ids[-8:],
+            "answered_question_ids": context.answered_question_ids[-16:],
+            "question_ledger": [_bound_structure(item, max_chars=1000) for item in context.question_ledger[-12:]],
+            "evidence_cache": evidence,
+            "last_blueprint": _bound_structure(context.last_blueprint, max_chars=5000),
+            "turns": turns,
+        }
+
+    def status(self) -> dict[str, int]:
+        return {
+            "memory_sessions": len(self._memory),
+            "max_sessions": self.max_sessions,
+            "max_turns": self.max_turns,
+        }
+
+    def _path(self, session_id: str) -> Path:
+        return self.root / session_id / "context.json"
+
+    def _remember(self, context: SessionContext) -> None:
+        self._memory[context.session_id] = (time.monotonic() + self.ttl_seconds, context)
+        self._memory.move_to_end(context.session_id)
+        while len(self._memory) > self.max_sessions:
+            self._memory.popitem(last=False)
+
+
+def _bound_structure(value: Any, *, max_chars: int) -> Any:
+    """Bound persistent helper state without converting it into an unbounded transcript."""
+    if isinstance(value, str):
+        return value[:max_chars]
+    if isinstance(value, list):
+        return [_bound_structure(item, max_chars=max(128, max_chars // max(1, min(len(value), 16)))) for item in value[-32:]]
+    if isinstance(value, dict):
+        bounded: dict[str, Any] = {}
+        per_item = max(128, max_chars // max(1, min(len(value), 32)))
+        for key, item in list(value.items())[-32:]:
+            bounded[str(key)[:160]] = _bound_structure(item, max_chars=per_item)
+        return bounded
+    return value

runtime/kb.py

@@ -0,0 +1,328 @@
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import tempfile
+import threading
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+from .schemas import KBHit
+from .security import contains_internal_implementation, redact_text
+
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS kb_pages (
+  kb_id TEXT PRIMARY KEY,
+  question TEXT NOT NULL,
+  short_answer TEXT NOT NULL,
+  body TEXT NOT NULL,
+  search_terms TEXT NOT NULL DEFAULT '',
+  answer_boundary TEXT NOT NULL DEFAULT '',
+  target TEXT NOT NULL DEFAULT '',
+  public_status TEXT NOT NULL,
+  implementation_status TEXT NOT NULL,
+  needs_review INTEGER NOT NULL DEFAULT 0,
+  source_url TEXT NOT NULL DEFAULT '',
+  verified_at TEXT NOT NULL DEFAULT ''
+);
+CREATE VIRTUAL TABLE IF NOT EXISTS kb_fts USING fts5(
+  kb_id UNINDEXED,
+  question,
+  short_answer,
+  body,
+  search_terms,
+  tokenize='unicode61'
+);
+"""
+MIN_EVIDENCE_SCORE = 5.0
+QUERY_ALIASES: dict[str, tuple[str, ...]] = {
+    "credit": ("クレジット", "残高", "付与", "決済"),
+    "billing": ("料金", "価格", "費用", "プラン"),
+    "account": ("アカウント", "ログイン", "認証", "退会", "削除"),
+    "webhook-gateway": ("Webhook Gateway", "webhook", "配送", "再送", "復旧"),
+    "astera": ("Astera", "アステラ", "判断材料", "主役AI"),
+    "api": ("API", "APIキー", "連携", "エンドポイント"),
+    "procedure": ("方法", "手順", "確認"),
+    "troubleshooting": ("不具合", "エラー", "反映されない", "確認"),
+    "pricing": ("料金", "価格", "いくら", "費用"),
+    "comparison": ("違い", "比較"),
+}
+QUERY_STOP_TERMS = {
+    "すか",
+    "ですか",
+    "ますか",
+    "現在",
+    "system",
+    "prompt",
+    "internal",
+    "admin",
+    "env",
+    "内容",
+    "全部",
+    "全部出して",
+    "教えて",
+    "ください",
+}
+
+
+@dataclass(slots=True)
+class SnapshotInfo:
+    version: str
+    path: Path
+
+
+class KBIndex:
+    def __init__(self, root: Path, *, cache_ttl_seconds: int = 120, cache_max_entries: int = 256):
+        self.root = root / "kb"
+        self.root.mkdir(parents=True, exist_ok=True)
+        self._connection: sqlite3.Connection | None = None
+        self._version: str | None = None
+        self._cache_ttl_seconds = cache_ttl_seconds
+        self._cache_max_entries = cache_max_entries
+        self._query_cache: OrderedDict[tuple[str, str, int], tuple[float, list[KBHit]]] = OrderedDict()
+        self._lock = threading.RLock()
+
+    def _manifest_path(self) -> Path:
+        return self.root / "manifest.json"
+
+    def current(self) -> SnapshotInfo | None:
+        with self._lock:
+            path = self._manifest_path()
+            if not path.exists():
+                return None
+            manifest = json.loads(path.read_text(encoding="utf-8"))
+            snapshot = self.root / "snapshots" / manifest["version"] / "kb.sqlite"
+            return SnapshotInfo(version=manifest["version"], path=snapshot)
+
+    def open(self) -> bool:
+        with self._lock:
+            info = self.current()
+            if not info or not info.path.exists():
+                return False
+            if self._connection is not None and self._version == info.version:
+                return True
+            new = sqlite3.connect(f"file:{info.path}?mode=ro&immutable=1", uri=True, check_same_thread=False)
+            new.row_factory = sqlite3.Row
+            old = self._connection
+            self._connection = new
+            self._version = info.version
+            self._query_cache.clear()
+            if old is not None:
+                old.close()
+            return True
+
+    def search(self, query: str, *, limit: int = 5) -> list[KBHit]:
+        with self._lock:
+            if not self.open() or self._connection is None or not self._version:
+                return []
+            normalized_query = " ".join(query.split())[:1000]
+            expanded_terms = self._expand_terms(normalized_query)
+            expanded_query = " ".join(expanded_terms)
+            cache_key = (self._version, expanded_query, limit)
+            now = time.monotonic()
+            cached = self._query_cache.get(cache_key)
+            if cached and cached[0] > now:
+                self._query_cache.move_to_end(cache_key)
+                return [KBHit.model_validate(item.model_dump()) for item in cached[1]]
+            if cached:
+                self._query_cache.pop(cache_key, None)
+
+            terms = [part.strip().replace("%", "").replace("_", "") for part in expanded_terms if part.strip()][:20]
+            if not terms:
+                return []
+            score_parts: list[str] = []
+            where_parts: list[str] = []
+            score_params: list[Any] = []
+            where_params: list[Any] = []
+            for term in terms:
+                pattern = f"%{term}%"
+                score_parts.append(
+                    "(CASE WHEN question LIKE ? THEN 12 ELSE 0 END + "
+                    "CASE WHEN search_terms LIKE ? THEN 10 ELSE 0 END + "
+                    "CASE WHEN short_answer LIKE ? THEN 5 ELSE 0 END + "
+                    "CASE WHEN body LIKE ? THEN 2 ELSE 0 END)"
+                )
+                score_params.extend([pattern, pattern, pattern, pattern])
+                where_parts.append("(question LIKE ? OR search_terms LIKE ? OR short_answer LIKE ? OR body LIKE ?)")
+                where_params.extend([pattern, pattern, pattern, pattern])
+            sql = (
+                "SELECT *, (" + " + ".join(score_parts) + ") AS score FROM kb_pages WHERE "
+                + " OR ".join(where_parts)
+                + " ORDER BY score DESC, kb_id ASC LIMIT ?"
+            )
+            params = [*score_params, *where_params, limit]
+            rows = self._connection.execute(sql, params).fetchall()
+            hits: list[KBHit] = []
+            for row in rows:
+                score = float(row["score"] or 0.0)
+                if score < MIN_EVIDENCE_SCORE:
+                    continue
+                hits.append(
+                    KBHit(
+                        kb_id=row["kb_id"],
+                        question=row["question"],
+                        short_answer=row["short_answer"],
+                        body=row["body"],
+                        score=score,
+                        answer_boundary=row["answer_boundary"],
+                        target=row["target"],
+                    )
+                )
+            self._query_cache[cache_key] = (now + self._cache_ttl_seconds, hits)
+            self._query_cache.move_to_end(cache_key)
+            while len(self._query_cache) > self._cache_max_entries:
+                self._query_cache.popitem(last=False)
+            return [KBHit.model_validate(item.model_dump()) for item in hits]
+
+    def cache_status(self) -> dict[str, int]:
+        with self._lock:
+            return {"entries": len(self._query_cache), "max_entries": self._cache_max_entries}
+
+    def build_snapshot(self, *, version: str, pages: Iterable[dict[str, Any]]) -> SnapshotInfo:
+        with self._lock:
+            snapshot_dir = self.root / "snapshots" / version
+            snapshot_dir.mkdir(parents=True, exist_ok=True)
+            fd, temp_name = tempfile.mkstemp(suffix=".sqlite", dir=snapshot_dir)
+            os.close(fd)
+            temp = Path(temp_name)
+            connection = sqlite3.connect(temp)
+            try:
+                connection.executescript(SCHEMA)
+                accepted = 0
+                for page in pages:
+                    normalized = normalize_page(page)
+                    if normalized is None:
+                        continue
+                    connection.execute("INSERT INTO kb_pages VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", normalized)
+                    connection.execute(
+                        "INSERT INTO kb_fts VALUES (?, ?, ?, ?, ?)",
+                        (normalized[0], normalized[1], normalized[2], normalized[3], normalized[4]),
+                    )
+                    accepted += 1
+                connection.commit()
+                integrity = connection.execute("PRAGMA integrity_check").fetchone()[0]
+                if integrity != "ok":
+                    raise RuntimeError(f"SQLite integrity check failed: {integrity}")
+                if accepted == 0:
+                    raise RuntimeError("snapshot contains no publishable KB pages")
+            finally:
+                connection.close()
+            final = snapshot_dir / "kb.sqlite"
+            os.replace(temp, final)
+            manifest_tmp = self.root / ".manifest.tmp"
+            manifest_tmp.write_text(json.dumps({"version": version, "page_count": accepted}), encoding="utf-8")
+            os.replace(manifest_tmp, self._manifest_path())
+            self._query_cache.clear()
+            return SnapshotInfo(version=version, path=final)
+
+    @staticmethod
+    def _expand_terms(query: str) -> list[str]:
+        raw = [part for part in query.split() if part][:12]
+        expanded: list[str] = []
+        for term in raw:
+            normalized = term.strip()
+            key = normalized.lower()
+            if not normalized or key in QUERY_STOP_TERMS:
+                continue
+            if normalized not in expanded:
+                expanded.append(normalized)
+            for alias in QUERY_ALIASES.get(key, ()):
+                if alias not in expanded:
+                    expanded.append(alias)
+        return expanded[:20]
+
+
+def _lines(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [line.strip() for line in value.splitlines() if line.strip()]
+    if isinstance(value, list):
+        result: list[str] = []
+        for item in value:
+            result.extend(_lines(item))
+        return result
+    if isinstance(value, dict):
+        return [f"{key}: {item}" for key, item in value.items() if str(item).strip()]
+    text = str(value).strip()
+    return [text] if text else []
+
+
+def _section(title: str, value: Any, *, numbered: bool = False) -> str:
+    values = _lines(value)
+    if not values:
+        return ""
+    if numbered:
+        content = "\n".join(f"{index}. {item}" for index, item in enumerate(values, start=1))
+    else:
+        content = "\n".join(f"- {item}" for item in values)
+    return f"## {title}\n\n{content}"
+
+
+def compose_structured_body(page: dict[str, Any]) -> str:
+    sections = [
+        _section("目的・概要", page.get("目的")),
+        _section("理由", page.get("理由")),
+        _section("前提条件", page.get("前提条件")),
+        _section("利用条件", page.get("利用条件")),
+        _section("手順", page.get("手順"), numbered=True),
+        _section("条件", page.get("条件")),
+        _section("例外", page.get("例外")),
+        _section("障害症状", page.get("障害症状")),
+        _section("考えられる原因", page.get("原因")),
+        _section("確認方法", page.get("確認方法"), numbered=True),
+        _section("解決手順", page.get("解決手順"), numbered=True),
+        _section("完了確認", page.get("完了確認")),
+        _section("追加質問への対応", page.get("追加質問")),
+        _section("関連KB", page.get("関連KB")),
+    ]
+    return "\n\n".join(section for section in sections if section).strip()
+
+
+def _search_terms(page: dict[str, Any]) -> str:
+    values: list[str] = []
+    for key in ("製品", "システム", "カテゴリ", "質問種別", "検索語", "同義語", "追加質問"):
+        values.extend(_lines(page.get(key)))
+    return " ".join(dict.fromkeys(values))
+
+
+def _answer_boundary(page: dict[str, Any]) -> str:
+    values = [*_lines(page.get("回答境界")), *_lines(page.get("禁止回答"))]
+    return "\n".join(dict.fromkeys(values))
+
+
+def normalize_page(page: dict[str, Any]) -> tuple[Any, ...] | None:
+    if page.get("公開状態") != "公開":
+        return None
+    if page.get("実装状態") not in {"実装済み", "文書確認済み"}:
+        return None
+    if page.get("要再確認") in (True, "__YES__", 1):
+        return None
+    question = redact_text(str(page.get("質問", ""))).text.strip()
+    short = redact_text(str(page.get("短い回答", ""))).text.strip()
+    raw_body = str(page.get("本文", "")).strip() or compose_structured_body(page)
+    body = redact_text(raw_body).text.strip()
+    boundary = redact_text(_answer_boundary(page)).text.strip()
+    if not question or not short or not body:
+        return None
+    if contains_internal_implementation("\n".join((question, short, body, boundary))):
+        return None
+    return (
+        str(page.get("id") or page.get("url") or question),
+        question,
+        short,
+        body,
+        _search_terms(page),
+        boundary,
+        ",".join(page.get("対象", [])) if isinstance(page.get("対象"), list) else str(page.get("対象", "")),
+        str(page.get("公開状態")),
+        str(page.get("実装状態")),
+        0,
+        str(page.get("url", "")),
+        str(page.get("確認日", "")),
+    )

runtime/model.py

@@ -0,0 +1,152 @@
+from __future__ import annotations
+
+import json
+import threading
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+try:
+    import spaces
+except ImportError:
+    spaces = None
+
+from .config import Settings
+
+
+def _gpu_decorator(function: Callable[..., str]) -> Callable[..., str]:
+    if spaces is None:
+        return function
+    return spaces.GPU(duration=45)(function)
+
+
+_MODEL_LOCK = threading.Lock()
+_MODEL: Any = None
+_TOKENIZER: Any = None
+
+
+@_gpu_decorator
+def _generate_gpu(model_id: str, revision: str, packet: str, max_new_tokens: int) -> str:
+    global _MODEL, _TOKENIZER
+    with _MODEL_LOCK:
+        if _MODEL is None or _TOKENIZER is None:
+            from transformers import AutoModelForCausalLM, AutoTokenizer
+
+            _TOKENIZER = AutoTokenizer.from_pretrained(model_id, revision=revision, trust_remote_code=False)
+            _MODEL = AutoModelForCausalLM.from_pretrained(
+                model_id,
+                revision=revision,
+                trust_remote_code=False,
+                torch_dtype="auto",
+                device_map="auto",
+            )
+        instruction = (
+            "You are only the Japanese response-composition component inside Astera Customer AI. "
+            "You do not decide product facts, routing, search, task scope, actions, or completion. "
+            "The support_packet already contains decomposed question tasks, search plans, verified KB evidence, and an answer blueprint. "
+            "Compose a specific and polite answer from that material only. Answer every question task that has evidence. "
+            "For a task without evidence, keep it in unresolved_task_ids and ask only the task-specific missing information supplied by the blueprint. "
+            "Preserve the cached user goal and active topic. Do not repeat answered questions. "
+            "Never invent product facts, reveal private implementation, identify the model/provider, or claim an action was executed. "
+            "When repair is present, correct only the listed violations and do not broaden the response. "
+            "Return JSON only with keys: answer, user_goal, active_topic, answered_task_ids, unresolved_task_ids, used_evidence_ids, needs_clarification."
+        )
+        messages = [{"role": "user", "content": instruction + "\n" + packet}]
+        text = _TOKENIZER.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+        inputs = _TOKENIZER(text, return_tensors="pt").to(_MODEL.device)
+        outputs = _MODEL.generate(**inputs, max_new_tokens=max_new_tokens, do_sample=False)
+        generated = outputs[0][inputs["input_ids"].shape[1] :]
+        return _TOKENIZER.decode(generated, skip_special_tokens=True)
+
+
+class GPUUsageLedger:
+    def __init__(self, root: Path, budget_seconds: int):
+        self.path = root / "runtime" / "gpu-usage.jsonl"
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.budget_seconds = budget_seconds
+
+    def used_seconds(self) -> float:
+        if not self.path.exists():
+            return 0.0
+        cutoff = time.time() - 86400
+        total = 0.0
+        for line in self.path.read_text(encoding="utf-8").splitlines():
+            try:
+                row = json.loads(line)
+                if float(row["timestamp"]) >= cutoff:
+                    total += float(row["seconds"])
+            except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+                continue
+        return total
+
+    def can_use(self, reserve_seconds: int = 45) -> bool:
+        return self.used_seconds() + reserve_seconds <= self.budget_seconds
+
+    def record(self, seconds: float) -> None:
+        with self.path.open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps({"timestamp": time.time(), "seconds": seconds}) + "\n")
+
+
+class ConversationLanguageEngine:
+    REQUIRED_PACKET_KEYS = {"message", "conversation", "support_packet", "response_rules"}
+
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self.ledger = GPUUsageLedger(settings.data_root, settings.gpu_daily_budget_seconds)
+
+    def available(self) -> bool:
+        return bool(self.settings.enable_model and self.settings.model_revision and self.ledger.can_use())
+
+    def execute(self, packet: dict[str, Any]) -> dict[str, Any]:
+        missing = sorted(self.REQUIRED_PACKET_KEYS.difference(packet))
+        if missing:
+            raise ValueError("support_packet_missing:" + ",".join(missing))
+        if not self.available():
+            raise RuntimeError("model_unavailable_or_budget_exhausted")
+        support_packet = packet.get("support_packet")
+        if not isinstance(support_packet, dict):
+            raise ValueError("support_packet_invalid")
+        question_tasks = support_packet.get("question_tasks")
+        evidence = support_packet.get("evidence")
+        blueprint = support_packet.get("blueprint")
+        if not isinstance(question_tasks, list) or not question_tasks:
+            raise ValueError("support_packet_invalid:question_tasks")
+        if not isinstance(evidence, list) or not isinstance(blueprint, dict):
+            raise ValueError("support_packet_invalid:evidence_or_blueprint")
+
+        serialized = json.dumps(packet, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
+        started = time.monotonic()
+        raw = _generate_gpu(self.settings.model_id, self.settings.model_revision, serialized, 900)
+        self.ledger.record(time.monotonic() - started)
+        parsed = self._parse_json(raw)
+        self._validate_output(parsed)
+        return parsed
+
+    @staticmethod
+    def _validate_output(parsed: dict[str, Any]) -> None:
+        if not isinstance(parsed.get("answer"), str) or not parsed["answer"].strip():
+            raise ValueError("model_schema_invalid:answer")
+        for key in ("user_goal", "active_topic"):
+            if not isinstance(parsed.get(key), str):
+                raise ValueError(f"model_schema_invalid:{key}")
+        for key in ("answered_task_ids", "unresolved_task_ids", "used_evidence_ids"):
+            if not isinstance(parsed.get(key), list) or not all(isinstance(item, str) for item in parsed[key]):
+                raise ValueError(f"model_schema_invalid:{key}")
+        if not isinstance(parsed.get("needs_clarification"), bool):
+            raise ValueError("model_schema_invalid:needs_clarification")
+
+    @staticmethod
+    def _parse_json(raw: str) -> dict[str, Any]:
+        text = raw.strip()
+        if text.startswith("```"):
+            text = text.split("\n", 1)[-1]
+            if text.endswith("```"):
+                text = text[:-3]
+        parsed = json.loads(text.strip())
+        if not isinstance(parsed, dict):
+            raise ValueError("model_schema_invalid:root")
+        return parsed
+
+
+ControlledLanguageEngine = ConversationLanguageEngine
+DialogueModel = ConversationLanguageEngine

runtime/notion.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+
+class NotionSyncError(RuntimeError):
+    pass
+
+
+def _rich_text(value: Any) -> str:
+    if not isinstance(value, list):
+        return ""
+    return "".join(str(item.get("plain_text", "")) for item in value if isinstance(item, dict))
+
+
+def _property_value(prop: dict[str, Any]) -> Any:
+    kind = prop.get("type")
+    value = prop.get(kind, {}) if kind else None
+    if kind in {"title", "rich_text"}:
+        return _rich_text(value)
+    if kind == "select":
+        return (value or {}).get("name", "")
+    if kind == "multi_select":
+        return [item.get("name", "") for item in (value or [])]
+    if kind == "checkbox":
+        return bool(value)
+    if kind == "date":
+        return (value or {}).get("start", "")
+    if kind == "url":
+        return value or ""
+    if kind == "status":
+        return (value or {}).get("name", "")
+    if kind == "number":
+        return value
+    if kind == "formula":
+        formula_type = (value or {}).get("type")
+        return (value or {}).get(formula_type) if formula_type else None
+    return value
+
+
+def _block_text(block: dict[str, Any]) -> str:
+    kind = block.get("type")
+    payload = block.get(kind, {}) if kind else {}
+    text = _rich_text(payload.get("rich_text", []))
+    if kind in {"bulleted_list_item", "numbered_list_item", "to_do"} and text:
+        return f"- {text}"
+    if kind and kind.startswith("heading_") and text:
+        return f"## {text}"
+    if kind == "code" and text:
+        language = payload.get("language", "text")
+        return f"```{language}\n{text}\n```"
+    return text
+
+
+class NotionClient:
+    def __init__(self, token: str, data_source_id: str, *, timeout_seconds: int = 20):
+        self.token = token
+        self.data_source_id = data_source_id
+        self.timeout_seconds = timeout_seconds
+        self.headers = {
+            "authorization": f"Bearer {token}",
+            "notion-version": "2025-09-03",
+            "content-type": "application/json",
+        }
+
+    async def fetch_pages(self) -> list[dict[str, Any]]:
+        if not self.token or not self.data_source_id:
+            raise NotionSyncError("notion_not_configured")
+        async with httpx.AsyncClient(timeout=self.timeout_seconds, headers=self.headers) as client:
+            rows = await self._query_all(client)
+            semaphore = asyncio.Semaphore(3)
+
+            async def hydrate(row: dict[str, Any]) -> dict[str, Any]:
+                async with semaphore:
+                    content = await self._fetch_blocks(client, row["id"])
+                    properties = {
+                        name: _property_value(value)
+                        for name, value in row.get("properties", {}).items()
+                        if isinstance(value, dict)
+                    }
+                    properties.update(
+                        {
+                            "id": row["id"],
+                            "url": row.get("url", ""),
+                            "本文": content,
+                        }
+                    )
+                    return properties
+
+            return await asyncio.gather(*(hydrate(row) for row in rows))
+
+    async def _query_all(self, client: httpx.AsyncClient) -> list[dict[str, Any]]:
+        results: list[dict[str, Any]] = []
+        cursor: str | None = None
+        while True:
+            payload: dict[str, Any] = {"page_size": 100}
+            if cursor:
+                payload["start_cursor"] = cursor
+            response = await self._request_with_retry(
+                client,
+                "POST",
+                f"https://api.notion.com/v1/data_sources/{self.data_source_id}/query",
+                json=payload,
+            )
+            body = response.json()
+            results.extend(body.get("results", []))
+            if not body.get("has_more"):
+                return results
+            cursor = body.get("next_cursor")
+            if not cursor:
+                raise NotionSyncError("notion_missing_cursor")
+
+    async def _fetch_blocks(self, client: httpx.AsyncClient, block_id: str) -> str:
+        lines: list[str] = []
+        cursor: str | None = None
+        while True:
+            params: dict[str, Any] = {"page_size": 100}
+            if cursor:
+                params["start_cursor"] = cursor
+            response = await self._request_with_retry(
+                client,
+                "GET",
+                f"https://api.notion.com/v1/blocks/{block_id}/children",
+                params=params,
+            )
+            body = response.json()
+            for block in body.get("results", []):
+                text = _block_text(block)
+                if text:
+                    lines.append(text)
+                if block.get("has_children"):
+                    child = await self._fetch_blocks(client, block["id"])
+                    if child:
+                        lines.append(child)
+            if not body.get("has_more"):
+                break
+            cursor = body.get("next_cursor")
+            if not cursor:
+                break
+        return "\n".join(lines).strip()
+
+    async def _request_with_retry(self, client: httpx.AsyncClient, method: str, url: str, **kwargs: Any) -> httpx.Response:
+        delay = 1.0
+        last_error: Exception | None = None
+        for _ in range(5):
+            try:
+                response = await client.request(method, url, **kwargs)
+                if response.status_code == 429:
+                    await asyncio.sleep(float(response.headers.get("retry-after", delay)))
+                    delay = min(delay * 2, 16)
+                    continue
+                if response.status_code >= 500:
+                    await asyncio.sleep(delay)
+                    delay = min(delay * 2, 16)
+                    continue
+                response.raise_for_status()
+                return response
+            except (httpx.TimeoutException, httpx.NetworkError, httpx.HTTPStatusError) as exc:
+                last_error = exc
+                await asyncio.sleep(delay)
+                delay = min(delay * 2, 16)
+        raise NotionSyncError(f"notion_request_failed: {last_error}")

runtime/schemas.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from .security import validate_identifier
+
+
+JobStatus = Literal[
+    "received",
+    "accepted",
+    "queued_processing",
+    "processing",
+    "awaiting_clarification",
+    "retrying",
+    "degraded",
+    "completed",
+    "failed",
+]
+
+
+class MessagePayload(BaseModel):
+    session_id: str = Field(min_length=8, max_length=160)
+    message_id: str = Field(min_length=8, max_length=160)
+    message: str = Field(min_length=1, max_length=20000)
+    locale: Literal["ja-JP", "en"] = "ja-JP"
+    source: Literal["astera-hp", "astera-app"]
+
+    @field_validator("session_id", "message_id")
+    @classmethod
+    def safe_identifier(cls, value: str) -> str:
+        return validate_identifier(value)
+
+
+class ConversationTurn(BaseModel):
+    role: Literal["user", "assistant"]
+    text: str = Field(min_length=1, max_length=8000)
+    message_id: str = ""
+    kb_ids: list[str] = Field(default_factory=list)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class SessionContext(BaseModel):
+    session_id: str
+    user_goal: str = ""
+    active_topic: str = ""
+    confirmed_details: dict[str, Any] = Field(default_factory=dict)
+    unresolved_questions: list[str] = Field(default_factory=list)
+    last_kb_ids: list[str] = Field(default_factory=list)
+    turns: list[ConversationTurn] = Field(default_factory=list)
+    answered_question_ids: list[str] = Field(default_factory=list)
+    question_ledger: list[dict[str, Any]] = Field(default_factory=list)
+    evidence_cache: dict[str, dict[str, Any]] = Field(default_factory=dict)
+    last_blueprint: dict[str, Any] = Field(default_factory=dict)
+    updated_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class CloudEvent(BaseModel):
+    specversion: Literal["1.0"] = "1.0"
+    id: str = Field(min_length=8, max_length=160)
+    source: str = Field(min_length=3, max_length=300)
+    type: str = Field(min_length=3, max_length=160)
+    subject: str = Field(min_length=3, max_length=300)
+    time: datetime
+    datacontenttype: Literal["application/json"] = "application/json"
+    data: dict[str, Any]
+
+
+class JobRecord(BaseModel):
+    job_id: str
+    event_id: str
+    session_id: str
+    message_id: str
+    status: JobStatus
+    stage: str
+    request_hash: str
+    created_at: datetime
+    updated_at: datetime
+    attempts: int = 0
+    error_code: str | None = None
+    queue_event_id: str | None = None
+
+    @classmethod
+    def new(cls, *, job_id: str, event_id: str, payload: MessagePayload, request_hash: str) -> "JobRecord":
+        now = datetime.now(UTC)
+        return cls(
+            job_id=job_id,
+            event_id=event_id,
+            session_id=payload.session_id,
+            message_id=payload.message_id,
+            status="accepted",
+            stage="durable_accept",
+            request_hash=request_hash,
+            created_at=now,
+            updated_at=now,
+        )
+
+
+class JobResult(BaseModel):
+    job_id: str
+    session_id: str
+    status: Literal["completed", "awaiting_clarification", "failed"]
+    answer: str
+    kb_ids: list[str] = Field(default_factory=list)
+    ai_invoked: bool = False
+    clarification: str | None = None
+    facts: list[str] = Field(default_factory=list)
+    context_used: bool = False
+    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+
+class KBHit(BaseModel):
+    kb_id: str
+    question: str
+    short_answer: str
+    body: str
+    score: float
+    answer_boundary: str = ""
+    target: str = ""
+
+
+class NodeResponse(BaseModel):
+    request_id: str
+    ok: bool
+    result: dict[str, Any] = Field(default_factory=dict)
+    error_code: str | None = None
+    duration_ms: int = 0

runtime/security.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import re
+import time
+from dataclasses import dataclass
+from typing import Any
+
+EMAIL = re.compile(r"(?<![\w.+-])[\w.+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")
+PHONE = re.compile(r"(?<!\d)(?:\+?81[- ]?|0)\d{1,4}[- ]?\d{1,4}[- ]?\d{3,4}(?!\d)")
+CARD = re.compile(r"(?<!\d)(?:\d[ -]?){13,19}(?!\d)")
+JWT = re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b")
+TOKEN = re.compile(r"\b(?:sk|hf|ghp|github_pat|xox[baprs])[-_][A-Za-z0-9_-]{16,}\b", re.I)
+PRIVATE_KEY = re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----")
+INTERNAL_PATH = re.compile(r"(?:/internal/|src/(?:system|component|feature|part)/|\.env\b)", re.I)
+IDENTIFIER = re.compile(r"^[A-Za-z0-9_.:-]{8,160}$")
+PROMPT_INJECTION = re.compile(r"(?:ignore (?:all|previous) instructions|system prompt|developer message|前の指示を無視|システムプロンプト)", re.I)
+HIGH_ENTROPY = re.compile(r"\b[A-Za-z0-9_+/=-]{40,}\b")
+
+
+@dataclass(slots=True)
+class RedactionResult:
+    text: str
+    kinds: list[str]
+
+
+def _decode_secret(secret: str) -> bytes:
+    if secret.startswith("base64:"):
+        try:
+            return base64.b64decode(secret.removeprefix("base64:"), validate=True)
+        except ValueError:
+            return b""
+    return secret.encode("utf-8")
+
+
+def verify_standard_webhook(
+    raw_body: bytes,
+    event_id: str,
+    timestamp: str,
+    signature: str,
+    secret: str,
+    *,
+    tolerance_seconds: int = 300,
+) -> bool:
+    if not secret or not event_id or not timestamp or not signature:
+        return False
+    try:
+        ts = int(timestamp)
+        body_text = raw_body.decode("utf-8")
+    except (ValueError, UnicodeDecodeError):
+        return False
+    if tolerance_seconds and abs(int(time.time()) - ts) > tolerance_seconds:
+        return False
+    key = _decode_secret(secret)
+    if not key:
+        return False
+    expected = hmac.new(key, f"{event_id}.{timestamp}.{body_text}".encode("utf-8"), hashlib.sha256).digest()
+    candidates: list[bytes] = []
+    for item in signature.split():
+        version, separator, encoded = item.partition(",")
+        if version != "v1" or not separator or not encoded:
+            continue
+        try:
+            candidates.append(base64.b64decode(encoded, validate=True))
+        except ValueError:
+            continue
+    return any(hmac.compare_digest(expected, candidate) for candidate in candidates)
+
+
+def sign_standard_webhook(raw_body: bytes, event_id: str, timestamp: str, secret: str) -> str:
+    key = _decode_secret(secret)
+    if not key:
+        raise ValueError("standard_webhook_secret_invalid")
+    body_text = raw_body.decode("utf-8")
+    digest = hmac.new(key, f"{event_id}.{timestamp}.{body_text}".encode("utf-8"), hashlib.sha256).digest()
+    return "v1," + base64.b64encode(digest).decode("ascii")
+
+
+def verify_hmac(raw_body: bytes, timestamp: str, signature: str, secret: str, *, tolerance_seconds: int = 300) -> bool:
+    if not secret or not timestamp or not signature:
+        return False
+    try:
+        ts = int(timestamp)
+    except ValueError:
+        return False
+    if abs(int(time.time()) - ts) > tolerance_seconds:
+        return False
+    expected = hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
+    provided = signature.removeprefix("sha256=")
+    return hmac.compare_digest(expected, provided)
+
+
+def sign_hmac(raw_body: bytes, timestamp: str, secret: str) -> str:
+    return "sha256=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
+
+
+def canonical_json(value: Any) -> bytes:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str).encode()
+
+
+def redact_text(value: str) -> RedactionResult:
+    text = value
+    kinds: list[str] = []
+    for kind, pattern, replacement in (
+        ("private_key", PRIVATE_KEY, "<REDACTED_PRIVATE_KEY>"),
+        ("jwt", JWT, "<REDACTED_JWT>"),
+        ("token", TOKEN, "<REDACTED_TOKEN>"),
+        ("high_entropy", HIGH_ENTROPY, "<REDACTED_HIGH_ENTROPY>"),
+        ("email", EMAIL, "<EMAIL>"),
+        ("phone", PHONE, "<PHONE>"),
+        ("card", CARD, "<PAYMENT_NUMBER>"),
+    ):
+        text, count = pattern.subn(replacement, text)
+        if count:
+            kinds.append(kind)
+    return RedactionResult(text=text, kinds=sorted(set(kinds)))
+
+
+def sanitize_structure(value: Any) -> Any:
+    if isinstance(value, str):
+        return redact_text(value).text
+    if isinstance(value, list):
+        return [sanitize_structure(item) for item in value]
+    if isinstance(value, dict):
+        result: dict[str, Any] = {}
+        for key, item in value.items():
+            lowered = str(key).lower()
+            if any(word in lowered for word in ("password", "secret", "token", "authorization", "card")):
+                result[str(key)] = "<REDACTED>"
+            else:
+                result[str(key)] = sanitize_structure(item)
+        return result
+    return value
+
+
+def contains_internal_implementation(text: str) -> bool:
+    return bool(INTERNAL_PATH.search(text))
+
+
+def validate_identifier(value: str, *, field: str = "identifier") -> str:
+    if not IDENTIFIER.fullmatch(value):
+        raise ValueError(f"{field} contains unsupported characters")
+    return value
+
+
+def safe_candidate_phrase(value: str) -> bool:
+    clean = " ".join(value.split())
+    if not 3 <= len(clean) <= 120:
+        return False
+    if PROMPT_INJECTION.search(clean) or contains_internal_implementation(clean):
+        return False
+    if PRIVATE_KEY.search(clean) or JWT.search(clean) or TOKEN.search(clean) or HIGH_ENTROPY.search(clean):
+        return False
+    return True

runtime/service.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .config import Settings
+from .control import ConversationCore
+from .conversation import ConversationCache
+from .kb import KBIndex
+from .model import ConversationLanguageEngine
+from .notion import NotionClient
+from .schemas import CloudEvent, JobRecord, JobResult, MessagePayload
+from .security import canonical_json, redact_text, sanitize_structure, validate_identifier
+from .storage import ConflictError, JobStore
+from .support import FeedbackStore
+from .v8 import V8Supervisor
+
+
+class InternalEventApiClient:
+    def __init__(self, settings: Settings):
+        self.settings = settings
+
+    async def emit(self, event_type: str, subject: str, data: dict[str, Any]) -> None:
+        if not (
+            self.settings.internal_event_api_url
+            and self.settings.internal_event_api_token
+            and self.settings.internal_event_result_destination_id
+        ):
+            return
+        sanitized = sanitize_structure(data)
+        event_id = "evt_" + hashlib.sha256(
+            f"{event_type}:{subject}:{canonical_json(sanitized).hex()}".encode()
+        ).hexdigest()[:32]
+        payload = {
+            "eventId": event_id,
+            "eventType": event_type,
+            "sourceId": self.settings.internal_event_source_id,
+            "destinationId": self.settings.internal_event_result_destination_id,
+            "subject": subject,
+            "time": datetime.now(UTC).isoformat(),
+            "data": sanitized,
+        }
+        headers = {
+            "authorization": f"Bearer {self.settings.internal_event_api_token}",
+            "content-type": "application/json",
+        }
+        async with httpx.AsyncClient(
+            timeout=self.settings.internal_event_api_timeout_seconds
+        ) as client:
+            response = await client.post(
+                self.settings.internal_event_api_url,
+                json=payload,
+                headers=headers,
+            )
+            response.raise_for_status()
+
+
+class CustomerAIService:
+    def __init__(self, settings: Settings | None = None):
+        self.settings = settings or Settings.load()
+        self.settings.ensure_directories()
+        self.jobs = JobStore(self.settings.data_root)
+        self.kb = KBIndex(
+            self.settings.data_root,
+            cache_ttl_seconds=self.settings.kb_cache_ttl_seconds,
+            cache_max_entries=self.settings.kb_cache_max_entries,
+        )
+        self.v8 = V8Supervisor(self.settings)
+        self.engine = ConversationLanguageEngine(self.settings)
+        self.conversations = ConversationCache(
+            self.settings.data_root,
+            ttl_seconds=self.settings.session_cache_ttl_seconds,
+            max_sessions=self.settings.session_cache_max_sessions,
+            max_turns=self.settings.session_cache_max_turns,
+        )
+        self.feedback = FeedbackStore(self.settings.data_root)
+        self.core = ConversationCore(
+            v8=self.v8,
+            engine=self.engine,
+            cache=self.conversations,
+            search=self.kb.search,
+            feedback_store=self.feedback,
+        )
+        self.events = InternalEventApiClient(self.settings)
+        self.notion = NotionClient(
+            self.settings.notion_token, self.settings.notion_data_source_id
+        )
+        self._process_semaphore = asyncio.Semaphore(self.settings.process_concurrency)
+
+    async def startup(self) -> None:
+        try:
+            await self.v8.start()
+        except Exception:
+            pass
+        self.kb.open()
+
+    async def shutdown(self) -> None:
+        await self.v8.stop()
+
+    async def sync_notion_kb(self, version: str) -> dict[str, Any]:
+        pages = await self.notion.fetch_pages()
+        info = await asyncio.to_thread(
+            self.kb.build_snapshot, version=version, pages=pages
+        )
+        self.kb.open()
+        result = {
+            "version": info.version,
+            "path": str(info.path),
+            "source_pages": len(pages),
+        }
+        await self.events.emit(
+            "customer.ai.kb.update.applied", f"kb/{version}", result
+        )
+        return result
+
+    async def recover_once(self) -> dict[str, Any]:
+        recovered: list[str] = []
+        now = datetime.now(UTC)
+        for status_path in self.settings.data_root.glob("jobs/*/*/status.json"):
+            try:
+                record = JobRecord.model_validate_json(
+                    status_path.read_text(encoding="utf-8")
+                )
+            except Exception:
+                continue
+            age = (now - record.updated_at).total_seconds()
+            should_requeue = (
+                record.status in {"accepted", "queued_processing", "retrying"}
+                and age > 60
+            )
+            if record.status == "processing":
+                lease_path = status_path.parent / "lease.json"
+                if not lease_path.exists():
+                    should_requeue = age > self.settings.job_lease_seconds
+                else:
+                    try:
+                        lease = self.jobs.store.get_json(lease_path)
+                        should_requeue = datetime.fromisoformat(lease["expires_at"]) <= now
+                    except Exception:
+                        should_requeue = True
+            if not should_requeue:
+                continue
+            self.jobs.update_job(
+                record.job_id, status="retrying", stage="recovery_requeue"
+            )
+            await self.events.emit(
+                "customer.ai.job.requeue.requested",
+                f"job/{record.job_id}",
+                {"job_id": record.job_id},
+            )
+            recovered.append(record.job_id)
+        return {"recovered": recovered, "count": len(recovered)}
+
+    async def accept(self, event: CloudEvent) -> tuple[dict[str, Any], bool]:
+        if event.type != "customer.ai.message.requested":
+            raise ValueError("unsupported_event_type")
+        payload = MessagePayload.model_validate(event.data["message"])
+        if len(payload.message) > self.settings.max_input_chars:
+            raise ValueError("message_too_large")
+        redacted = redact_text(payload.message)
+        payload = payload.model_copy(update={"message": redacted.text})
+        validate_identifier(event.id, field="event_id")
+        job_id = str(
+            event.data.get("job_id")
+            or "job_" + hashlib.sha256(event.id.encode()).hexdigest()[:32]
+        )
+        validate_identifier(job_id, field="job_id")
+        record, created = self.jobs.accept(
+            job_id=job_id, event_id=event.id, payload=payload
+        )
+        await self.events.emit(
+            "customer.ai.job.accepted",
+            f"job/{job_id}",
+            {
+                "job_id": job_id,
+                "created": created,
+                "redaction_kinds": redacted.kinds,
+            },
+        )
+        return record.model_dump(mode="json"), created
+
+    async def process_job(self, job_id: str) -> dict[str, Any]:
+        existing = self.jobs.get_result(job_id)
+        if existing:
+            return existing
+        async with self._process_semaphore:
+            with self.jobs.store.lease(
+                self.jobs.job_dir(job_id) / "lease.json",
+                f"processor:{job_id}",
+                self.settings.job_lease_seconds,
+            ):
+                existing = self.jobs.get_result(job_id)
+                if existing:
+                    return existing
+                request = self.jobs.get_request(job_id)
+                self.jobs.update_job(
+                    job_id, status="processing", stage="support_preparation"
+                )
+                session_lease_path = (
+                    self.jobs.sessions_root / request.session_id / "lease.json"
+                )
+                try:
+                    with self.jobs.store.lease(
+                        session_lease_path,
+                        job_id,
+                        self.settings.session_lease_seconds,
+                    ):
+                        result = await self._run_pipeline(job_id, request)
+                except ConflictError:
+                    self.jobs.update_job(
+                        job_id, status="retrying", stage="session_busy"
+                    )
+                    return {"job_id": job_id, "status": "retrying", "retry_after": 2}
+                self.jobs.save_result(job_id, result)
+                self.jobs.update_job(
+                    job_id, status=result["status"], stage=result["status"]
+                )
+                await self.events.emit(
+                    "customer.ai.response.completed", f"job/{job_id}", result
+                )
+                return result
+
+    async def _run_pipeline(
+        self, job_id: str, request: MessagePayload
+    ) -> dict[str, Any]:
+        outcome = await self.core.execute(request=request)
+        return JobResult(
+            job_id=job_id,
+            session_id=request.session_id,
+            status=outcome.status,
+            answer=outcome.answer,
+            kb_ids=outcome.kb_ids,
+            ai_invoked=outcome.engine_invoked,
+            clarification=outcome.clarification,
+            facts=outcome.facts,
+            context_used=outcome.context_used,
+        ).model_dump(mode="json") | {
+            "analysis": outcome.analysis,
+            "violations": outcome.violations,
+            "processing_grade": outcome.processing_grade,
+            "question_tasks": outcome.question_tasks,
+            "blueprint": outcome.blueprint,
+            "repair_attempted": outcome.repair_attempted,
+            "feedback_candidate_id": outcome.feedback_candidate_id,
+            "execution": outcome.execution,
+        }
+
+    def readiness(self) -> dict[str, Any]:
+        return {
+            "data_root": self.settings.data_root.exists()
+            and os_access(self.settings.data_root),
+            "v8": bool(self.v8.process and self.v8.process.returncode is None),
+            "kb": self.kb.current() is not None,
+            "model_enabled": self.settings.enable_model,
+            "model_revision_pinned": bool(self.settings.model_revision),
+            "conversation_cache": self.conversations.status(),
+            "kb_cache": self.kb.cache_status(),
+            "feedback_store": self.feedback.root.exists(),
+            "internal_event_api": {
+                "configured": bool(
+                    self.settings.internal_event_api_url
+                    and self.settings.internal_event_api_token
+                    and self.settings.internal_event_result_destination_id
+                ),
+                "source_id": self.settings.internal_event_source_id,
+                "result_destination_id": self.settings.internal_event_result_destination_id,
+            },
+            "support_pipeline": "astera-derived-document-task-search-evidence-blueprint",
+        }
+
+
+def os_access(path: Path) -> bool:
+    try:
+        probe = path / "temporary" / ".ready-probe"
+        probe.parent.mkdir(parents=True, exist_ok=True)
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+        return True
+    except OSError:
+        return False

runtime/storage.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Any, Iterator
+
+from .schemas import JobRecord, MessagePayload
+from .security import canonical_json
+
+
+class ConflictError(RuntimeError):
+    pass
+
+
+class NotFoundError(RuntimeError):
+    pass
+
+
+@dataclass(slots=True)
+class Lease:
+    path: Path
+    owner: str
+    expires_at: datetime
+
+
+class AtomicStore:
+    def __init__(self, root: Path):
+        self.root = root
+        self.root.mkdir(parents=True, exist_ok=True)
+
+    @staticmethod
+    def _write_atomic(path: Path, data: bytes) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
+        try:
+            with os.fdopen(fd, "wb") as handle:
+                handle.write(data)
+                handle.flush()
+                os.fsync(handle.fileno())
+            os.replace(temp_name, path)
+        finally:
+            if os.path.exists(temp_name):
+                os.unlink(temp_name)
+
+    def create_once(self, path: Path, data: bytes) -> bool:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+        except FileExistsError:
+            return False
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        return True
+
+    def put_json(self, path: Path, value: Any) -> None:
+        self._write_atomic(path, canonical_json(value))
+
+    def get_json(self, path: Path) -> Any:
+        try:
+            return json.loads(path.read_text(encoding="utf-8"))
+        except FileNotFoundError as exc:
+            raise NotFoundError(str(path)) from exc
+
+    @contextmanager
+    def lease(self, path: Path, owner: str, ttl_seconds: int) -> Iterator[Lease]:
+        now = datetime.now(UTC)
+        expires = now + timedelta(seconds=ttl_seconds)
+        payload = {"owner": owner, "heartbeat_at": now.isoformat(), "expires_at": expires.isoformat()}
+        created = self.create_once(path, canonical_json(payload))
+        if not created:
+            current = self.get_json(path)
+            current_expiry = datetime.fromisoformat(current["expires_at"])
+            if current_expiry > now:
+                raise ConflictError(f"lease owned by {current.get('owner')}")
+            stale = path.with_suffix(f".stale.{int(time.time())}.json")
+            try:
+                os.replace(path, stale)
+            except FileNotFoundError:
+                pass
+            if not self.create_once(path, canonical_json(payload)):
+                raise ConflictError("lease was concurrently recovered")
+        lease = Lease(path=path, owner=owner, expires_at=expires)
+        try:
+            yield lease
+        finally:
+            try:
+                current = self.get_json(path)
+                if current.get("owner") == owner:
+                    path.unlink(missing_ok=True)
+            except NotFoundError:
+                pass
+
+    def heartbeat(self, lease: Lease, ttl_seconds: int) -> None:
+        current = self.get_json(lease.path)
+        if current.get("owner") != lease.owner:
+            raise ConflictError("lease ownership changed")
+        now = datetime.now(UTC)
+        expires = now + timedelta(seconds=ttl_seconds)
+        self.put_json(
+            lease.path,
+            {"owner": lease.owner, "heartbeat_at": now.isoformat(), "expires_at": expires.isoformat()},
+        )
+        lease.expires_at = expires
+
+
+class JobStore:
+    def __init__(self, root: Path):
+        self.store = AtomicStore(root)
+        self.jobs_root = root / "jobs"
+        self.sessions_root = root / "sessions"
+
+    def job_dir(self, job_id: str) -> Path:
+        return self.jobs_root / job_id[:2] / job_id
+
+    def accept(self, *, job_id: str, event_id: str, payload: MessagePayload) -> tuple[JobRecord, bool]:
+        job_dir = self.job_dir(job_id)
+        request_data = payload.model_dump(mode="json")
+        request_hash = hashlib.sha256(canonical_json(request_data)).hexdigest()
+        created = self.store.create_once(job_dir / "request.json", canonical_json(request_data))
+        if not created:
+            existing_hash = hashlib.sha256((job_dir / "request.json").read_bytes()).hexdigest()
+            if existing_hash != request_hash:
+                raise ConflictError("job id reused with different payload")
+            return JobRecord.model_validate(self.store.get_json(job_dir / "status.json")), False
+        record = JobRecord.new(job_id=job_id, event_id=event_id, payload=payload, request_hash=request_hash)
+        self.store.put_json(job_dir / "status.json", record.model_dump(mode="json"))
+        self.store.create_once(
+            self.sessions_root / payload.session_id / "events" / f"{payload.message_id}.json",
+            canonical_json({"type": "message", "job_id": job_id, **request_data}),
+        )
+        return record, True
+
+    def get_job(self, job_id: str) -> JobRecord:
+        return JobRecord.model_validate(self.store.get_json(self.job_dir(job_id) / "status.json"))
+
+    def get_request(self, job_id: str) -> MessagePayload:
+        return MessagePayload.model_validate(self.store.get_json(self.job_dir(job_id) / "request.json"))
+
+    def update_job(self, job_id: str, **changes: Any) -> JobRecord:
+        record = self.get_job(job_id)
+        data = record.model_dump()
+        data.update(changes)
+        data["updated_at"] = datetime.now(UTC)
+        updated = JobRecord.model_validate(data)
+        self.store.put_json(self.job_dir(job_id) / "status.json", updated.model_dump(mode="json"))
+        return updated
+
+    def save_result(self, job_id: str, result: dict[str, Any]) -> None:
+        self.store.put_json(self.job_dir(job_id) / "result.json", result)
+
+    def get_result(self, job_id: str) -> dict[str, Any] | None:
+        path = self.job_dir(job_id) / "result.json"
+        return self.store.get_json(path) if path.exists() else None
+
+    def save_insight(self, job_id: str, insight: dict[str, Any]) -> None:
+        self.store.put_json(self.job_dir(job_id) / "insight.json", insight)
+
+    def append_session_state(self, session_id: str, job_id: str, state: dict[str, Any]) -> None:
+        session_dir = self.sessions_root / session_id
+        self.store.create_once(
+            session_dir / "events" / f"state-{job_id}.json",
+            canonical_json({"type": "state", "job_id": job_id, "state": state}),
+        )
+        self.store.put_json(session_dir / "state.json", state)
+
+    def get_session_state(self, session_id: str) -> dict[str, Any]:
+        path = self.sessions_root / session_id / "state.json"
+        if not path.exists():
+            return {}
+        return self.store.get_json(path)

runtime/support.py

@@ -0,0 +1,622 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import re
+import threading
+import unicodedata
+from dataclasses import asdict, dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any, Callable, Iterable
+
+from .security import contains_internal_implementation, redact_text, sanitize_structure
+
+
+KNOWN_SUBJECTS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("astera-app", re.compile(r"Astera[- ]?app|アステラアプリ|アプリ", re.I)),
+    ("webhook-gateway", re.compile(r"Webhook\s*Gateway|webhook|配送|再送|リプレイ", re.I)),
+    ("astera", re.compile(r"Astera|アステラ", re.I)),
+    ("api", re.compile(r"API|APIキー|エンドポイント|連携", re.I)),
+    ("billing", re.compile(r"料金|価格|支払|決済|請求|クレジット|残高|プラン", re.I)),
+    ("account", re.compile(r"アカウント|ログイン|認証|パスワード|退会|解約|削除", re.I)),
+    ("support", re.compile(r"問い合わせ|質問|回答|サポート|Customer\s*AI", re.I)),
+)
+
+INTENTS: tuple[tuple[str, re.Pattern[str]], ...] = (
+    ("comparison", re.compile(r"違い|比較|どちら|何が異なる|vs\b", re.I)),
+    ("troubleshooting", re.compile(r"エラー|動かない|できない|反映されない|届かない|失敗|不具合|直し|確認すれば", re.I)),
+    ("procedure", re.compile(r"方法|手順|どうやって|どこから|どこを|何を確認|確認方法|設定|使い方|始め方|導入", re.I)),
+    ("pricing", re.compile(r"料金|価格|いくら|費用|課金|クレジット", re.I)),
+    ("contract", re.compile(r"契約|解約|退会|返金|更新|支払", re.I)),
+    ("availability", re.compile(r"使える|使えます|使えない|利用でき|対応|可能|できる|未実装|提供", re.I)),
+    ("limitation", re.compile(r"制限|上限|できない|禁止|対象外|条件", re.I)),
+    ("definition", re.compile(r"とは|何ですか|何なの|意味|概要", re.I)),
+)
+
+ANSWER_SHAPES = {
+    "comparison": "comparison",
+    "troubleshooting": "resolution_steps",
+    "procedure": "ordered_steps",
+    "pricing": "current_fact",
+    "contract": "conditions_and_steps",
+    "availability": "yes_no_with_conditions",
+    "limitation": "boundary",
+    "definition": "conclusion_and_detail",
+    "general": "conclusion_and_detail",
+}
+
+REQUIRED_EVIDENCE = {
+    "comparison": ("definition", "responsibility", "limitations"),
+    "troubleshooting": ("symptom", "cause", "check", "resolution", "completion_check"),
+    "procedure": ("prerequisites", "ordered_steps", "completion_check"),
+    "pricing": ("current_price", "conditions", "effective_date"),
+    "contract": ("current_terms", "conditions", "ordered_steps"),
+    "availability": ("implementation_status", "conditions", "limitations"),
+    "limitation": ("answer_boundary", "conditions", "exceptions"),
+    "definition": ("definition", "purpose", "scope"),
+    "general": ("confirmed_answer", "conditions"),
+}
+
+STOP_WORDS = {
+    "これ", "それ", "その", "この", "あれ", "あと", "また", "さらに", "について", "教えて", "ください",
+    "です", "ます", "したい", "できる", "できます", "どう", "どこ", "何", "なぜ", "場合", "もの", "こと",
+    "the", "a", "an", "is", "are", "what", "how", "can", "does", "please",
+}
+
+
+@dataclass(slots=True)
+class QuestionTask:
+    task_id: str
+    text: str
+    subject: str
+    intent: str
+    audience: str
+    answer_shape: str
+    search_terms: list[str]
+    required_evidence: list[str]
+    depends_on: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class SearchTask:
+    task_id: str
+    query: str
+    terms: list[str]
+    required_evidence: list[str]
+    priority_sources: list[str]
+    comparison_conditions: list[str]
+    verification_conditions: list[str]
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class EvidenceItem:
+    evidence_id: str
+    kb_id: str
+    task_ids: list[str]
+    question: str
+    short_answer: str
+    body: str
+    answer_boundary: str
+    target: str
+    score: float
+    source: str = "kb_search"
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class PreparedSupport:
+    normalized_message: str
+    analysis_dictionary: dict[str, Any]
+    tasks: list[QuestionTask]
+    search_tasks: list[SearchTask]
+    evidence: list[EvidenceItem]
+    blueprint: dict[str, Any]
+    processing_grade: str
+    model_required: bool
+
+    def as_packet(self) -> dict[str, Any]:
+        return {
+            "normalized_message": self.normalized_message,
+            "analysis_dictionary": self.analysis_dictionary,
+            "question_tasks": [item.as_dict() for item in self.tasks],
+            "search_tasks": [item.as_dict() for item in self.search_tasks],
+            "evidence": [item.as_dict() for item in self.evidence],
+            "blueprint": self.blueprint,
+            "processing_grade": self.processing_grade,
+        }
+
+
+@dataclass(slots=True)
+class ResponseValidation:
+    passed: bool
+    violations: list[str]
+    answered_task_ids: list[str]
+    unresolved_task_ids: list[str]
+    used_evidence_ids: list[str]
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def normalize_japanese(text: str) -> str:
+    normalized = unicodedata.normalize("NFKC", str(text or ""))
+    normalized = re.sub(r"[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]", "", normalized)
+    normalized = normalized.replace("｡", "。").replace("､", "、")
+    normalized = re.sub(r"[ \t]+", " ", normalized)
+    normalized = re.sub(r"\n{3,}", "\n\n", normalized)
+    return normalized.strip()
+
+
+def detect_subject(text: str, previous: str = "") -> str:
+    for subject, pattern in KNOWN_SUBJECTS:
+        if pattern.search(text):
+            return subject
+    return previous or "general"
+
+
+def detect_intent(text: str) -> str:
+    for intent, pattern in INTENTS:
+        if pattern.search(text):
+            return intent
+    return "general"
+
+
+def detect_audience(text: str, source: str) -> str:
+    if re.search(r"開発者|実装|コード|SDK|API|Webhook|JSON|HTTP|GitHub", text, re.I):
+        return "developer"
+    if re.search(r"法人|企業|スポンサー|投資|提携", text, re.I):
+        return "business"
+    return "registered_user" if source == "astera-app" else "general_user"
+
+
+def _split_document(text: str) -> list[str]:
+    lines = [re.sub(r"^\s*(?:[-*・]|\d+[.)．、]|[①-⑳])\s*", "", line).strip() for line in text.splitlines()]
+    lines = [line for line in lines if line] or [text]
+    candidates: list[tuple[str, bool]] = []
+    for line in lines:
+        for raw_part in re.split(r"(?<=[?？!！。])\s*", line):
+            for raw_item in re.split(r"\s*(?:それと|さらに|加えて|あと、|また、)\s*", raw_part):
+                item = raw_item.strip()
+                if not item:
+                    continue
+                question_mark = item.endswith(("?", "？"))
+                cleaned = item.strip(" \t。?？")
+                if not cleaned:
+                    continue
+                actionable = question_mark or detect_intent(cleaned) != "general" or bool(re.search(r"教えて|知りたい|確認したい", cleaned))
+                candidates.append((cleaned, actionable))
+    selected = [item for item, actionable in candidates if actionable]
+    if not selected:
+        selected = [item for item, _ in candidates]
+    deduped: list[str] = []
+    for item in selected:
+        if item not in deduped:
+            deduped.append(item)
+    return deduped[:8] or [text]
+
+
+def extract_search_terms(text: str, *, subject: str, intent: str, active_topic: str = "") -> list[str]:
+    working = normalize_japanese(text)
+    working = re.sub(r"(?:について|という|できますか|できるか|教えてください|教えて|とは|何ですか|どうですか)", " ", working)
+    working = re.sub(r"[?？!！。、,/:：()（）\[\]「」『』\-]+", " ", working)
+    working = re.sub(r"(?:は|が|を|に|で|と|や|へ|から|まで|より|の)", " ", working)
+    candidates = re.findall(r"[A-Za-z][A-Za-z0-9_.-]{1,40}|[一-龯ぁ-んァ-ヶー]{2,24}", working)
+    seeded = [subject, active_topic, intent, *candidates]
+    terms: list[str] = []
+    for term in seeded:
+        value = str(term or "").strip().lower()
+        if not value or value == "general" or value in STOP_WORDS or value in terms:
+            continue
+        terms.append(value)
+    return terms[:12]
+
+
+def build_analysis_dictionary(
+    *, message: str, context: dict[str, Any], analysis: dict[str, Any], tasks: list[QuestionTask]
+) -> dict[str, Any]:
+    missing: list[str] = []
+    details = dict(analysis.get("confirmed_details") or context.get("confirmed_details") or {})
+    if any(item.intent == "troubleshooting" for item in tasks):
+        if not details.get("error_code"):
+            missing.append("shown_error_or_symptom")
+        if not details.get("relative_time"):
+            missing.append("occurrence_timing")
+    premises = [str(key) for key in details]
+    if context.get("user_goal"):
+        premises.append("existing_user_goal")
+    return {
+        "purpose": str(analysis.get("user_goal") or context.get("user_goal") or message),
+        "targets": sorted({item.subject for item in tasks}),
+        "conditions": details,
+        "constraints": [
+            "use_confirmed_kb_only_for_product_facts",
+            "do_not_claim_unexecuted_actions",
+            "do_not_expose_private_implementation",
+            "answer_every_detected_question_or_mark_it_unresolved",
+        ],
+        "missing_information": list(dict.fromkeys(missing)),
+        "premises": list(dict.fromkeys(premises)),
+        "uncertainty": [] if tasks else ["question_decomposition_failed"],
+    }
+
+
+def _task_from_dict(item: dict[str, Any], index: int, *, source: str, previous_subject: str, active_topic: str) -> QuestionTask:
+    text = normalize_japanese(str(item.get("text") or item.get("question") or ""))
+    subject = str(item.get("subject") or detect_subject(text, previous_subject))
+    intent = str(item.get("intent") or detect_intent(text))
+    terms = [str(value).strip() for value in item.get("search_terms", []) if str(value).strip()]
+    if not terms:
+        terms = extract_search_terms(text, subject=subject, intent=intent, active_topic=active_topic)
+    required = item.get("required_evidence") or REQUIRED_EVIDENCE.get(intent, REQUIRED_EVIDENCE["general"])
+    return QuestionTask(
+        task_id=str(item.get("task_id") or f"q{index + 1}"),
+        text=text,
+        subject=subject,
+        intent=intent,
+        audience=str(item.get("audience") or detect_audience(text, source)),
+        answer_shape=str(item.get("answer_shape") or ANSWER_SHAPES.get(intent, "conclusion_and_detail")),
+        search_terms=terms,
+        required_evidence=[str(value) for value in required],
+        depends_on=[str(value) for value in item.get("depends_on", [])],
+    )
+
+
+def decompose_questions(
+    *, message: str, source: str, context: dict[str, Any], analysis: dict[str, Any]
+) -> list[QuestionTask]:
+    previous_subject = str(context.get("active_topic") or analysis.get("active_topic") or "")
+    active_topic = str(analysis.get("active_topic") or previous_subject)
+    supplied = analysis.get("question_tasks")
+    if isinstance(supplied, list) and supplied:
+        tasks = [
+            _task_from_dict(item, index, source=source, previous_subject=previous_subject, active_topic=active_topic)
+            for index, item in enumerate(supplied)
+            if isinstance(item, dict)
+        ]
+        if tasks:
+            return tasks[:8]
+    return [
+        _task_from_dict({"text": part}, index, source=source, previous_subject=previous_subject, active_topic=active_topic)
+        for index, part in enumerate(_split_document(message))
+    ]
+
+
+def plan_search(tasks: Iterable[QuestionTask], *, user_goal: str, active_topic: str) -> list[SearchTask]:
+    del user_goal
+    plans: list[SearchTask] = []
+    for task in tasks:
+        terms = list(task.search_terms)
+        for value in (task.subject, task.intent, active_topic):
+            value = str(value or "").strip().lower()
+            if value and value != "general" and value not in terms:
+                terms.append(value)
+        plans.append(
+            SearchTask(
+                task_id=task.task_id,
+                query=(" ".join(terms[:12]) or task.text)[:1000],
+                terms=terms[:12],
+                required_evidence=task.required_evidence,
+                priority_sources=["approved_notion_kb", "runtime_kb_snapshot", "bounded_session_evidence"],
+                comparison_conditions=["same_product_scope"] if task.intent == "comparison" else [],
+                verification_conditions=["public_status", "implementation_status", "answer_boundary", "evidence_path"],
+            )
+        )
+    return plans
+
+
+class EvidenceRetriever:
+    def __init__(self, search: Callable[..., list[Any]], *, max_parallel: int = 4, limit_per_task: int = 5):
+        self.search = search
+        self.max_parallel = max(1, min(max_parallel, 8))
+        self.limit_per_task = max(1, min(limit_per_task, 8))
+
+    async def retrieve(self, plans: list[SearchTask]) -> list[EvidenceItem]:
+        semaphore = asyncio.Semaphore(self.max_parallel)
+
+        async def run(plan: SearchTask) -> tuple[SearchTask, list[Any]]:
+            async with semaphore:
+                hits = await asyncio.to_thread(self.search, plan.query, limit=self.limit_per_task)
+                return plan, hits
+
+        results = await asyncio.gather(*(run(plan) for plan in plans))
+        merged: dict[str, EvidenceItem] = {}
+        for plan, hits in results:
+            for hit in hits:
+                kb_id = str(getattr(hit, "kb_id", ""))
+                if not kb_id:
+                    continue
+                item = merged.get(kb_id)
+                if item is None:
+                    item = EvidenceItem(
+                        evidence_id=f"kb:{kb_id}", kb_id=kb_id, task_ids=[],
+                        question=str(getattr(hit, "question", ""))[:1000],
+                        short_answer=str(getattr(hit, "short_answer", ""))[:2000],
+                        body=str(getattr(hit, "body", ""))[:5000],
+                        answer_boundary=str(getattr(hit, "answer_boundary", ""))[:1000],
+                        target=str(getattr(hit, "target", ""))[:300],
+                        score=float(getattr(hit, "score", 0.0)), source="kb_search",
+                    )
+                    merged[kb_id] = item
+                if plan.task_id not in item.task_ids:
+                    item.task_ids.append(plan.task_id)
+        return sorted(merged.values(), key=lambda item: (-item.score, item.kb_id))
+
+
+def _cached_evidence(context: dict[str, Any], tasks: list[QuestionTask]) -> list[EvidenceItem]:
+    cached = context.get("evidence_cache")
+    if not isinstance(cached, dict):
+        return []
+    result: list[EvidenceItem] = []
+    for evidence_id, raw in list(cached.items())[-16:]:
+        if not isinstance(raw, dict):
+            continue
+        combined = normalize_japanese(" ".join(str(raw.get(key) or "") for key in ("question", "short_answer", "answer_boundary"))).lower()
+        task_ids: list[str] = []
+        for task in tasks:
+            terms = [task.subject.lower(), *[term.lower() for term in task.search_terms]]
+            if any(term and term != "general" and term in combined for term in terms):
+                task_ids.append(task.task_id)
+        if not task_ids:
+            continue
+        kb_id = str(raw.get("kb_id") or str(evidence_id).removeprefix("kb:"))
+        result.append(
+            EvidenceItem(
+                evidence_id=str(evidence_id), kb_id=kb_id, task_ids=task_ids,
+                question=str(raw.get("question") or "")[:1000],
+                short_answer=str(raw.get("short_answer") or "")[:2000],
+                body="", answer_boundary=str(raw.get("answer_boundary") or "")[:1000],
+                target="", score=0.1, source="session_evidence_cache",
+            )
+        )
+    return result
+
+
+def _merge_evidence(fresh: list[EvidenceItem], cached: list[EvidenceItem]) -> list[EvidenceItem]:
+    merged = {item.evidence_id: item for item in fresh}
+    for item in cached:
+        existing = merged.get(item.evidence_id)
+        if existing is None:
+            merged[item.evidence_id] = item
+            continue
+        existing.task_ids = list(dict.fromkeys([*existing.task_ids, *item.task_ids]))
+    return sorted(merged.values(), key=lambda item: (-item.score, item.evidence_id))
+
+
+def _clarification_for(task: QuestionTask) -> str:
+    if task.intent == "troubleshooting":
+        return "表示されている症状またはエラー、現在の画面、直前に行った操作を確認すると原因と解決手順を絞れます。"
+    if task.intent in {"pricing", "contract"}:
+        return "料金・契約条件は現在の正本情報で確認する必要があるため、対象プランまたは契約状態を特定します。"
+    if task.intent == "comparison":
+        return "比較対象と、重視する条件を特定すると正確に違いを整理できます。"
+    if task.intent == "procedure":
+        return "対象の機能、現在の画面、実行したい操作を確認すると正しい順序で案内できます。"
+    return "対象の製品または機能と、確認したい点を特定すると正確に回答できます。"
+
+
+def _render_task_section(task: QuestionTask, evidence: list[EvidenceItem]) -> tuple[str, list[str], list[dict[str, Any]]]:
+    matched = [item for item in evidence if task.task_id in item.task_ids][:4]
+    if not matched:
+        return _clarification_for(task), [], []
+    blocks: list[str] = []
+    evidence_blocks: list[dict[str, Any]] = []
+    used: list[str] = []
+    for item in matched:
+        conclusion = item.short_answer.strip()
+        detail = item.body.strip()
+        text = conclusion
+        if detail and detail not in conclusion:
+            text += "\n\n" + detail
+        if task.answer_shape == "comparison" and len(matched) > 1:
+            text = f"#### {item.question or item.kb_id}\n\n{text}"
+        if text and text not in blocks:
+            blocks.append(text)
+        used.append(item.evidence_id)
+        evidence_blocks.append(
+            {
+                "evidence_id": item.evidence_id,
+                "question": item.question,
+                "conclusion": conclusion,
+                "detail": detail,
+                "answer_boundary": item.answer_boundary,
+                "source": item.source,
+            }
+        )
+    return "\n\n".join(blocks), list(dict.fromkeys(used)), evidence_blocks
+
+
+def _selected_runtime_skills(tasks: list[QuestionTask], context_used: bool) -> list[str]:
+    selected = ["japanese_normalization", "question_task_decomposition", "evidence_binding", "answer_coverage_validation"]
+    if context_used:
+        selected.append("conversation_reference_resolution")
+    if len(tasks) > 1:
+        selected.extend(["multi_question_management", "sectioned_document_composition"])
+    for task in tasks:
+        selected.append(f"audience_{task.audience}")
+        selected.append(f"shape_{task.answer_shape}")
+    return list(dict.fromkeys(selected))
+
+
+def build_blueprint(
+    *, tasks: list[QuestionTask], evidence: list[EvidenceItem], user_goal: str,
+    active_topic: str, locale: str, context_used: bool = False
+) -> dict[str, Any]:
+    sections: list[dict[str, Any]] = []
+    deterministic: list[str] = []
+    unresolved: list[str] = []
+    all_used: list[str] = []
+    for index, task in enumerate(tasks, start=1):
+        body, used, evidence_blocks = _render_task_section(task, evidence)
+        if not used:
+            unresolved.append(task.task_id)
+        all_used.extend(used)
+        sections.append(
+            {
+                "task_id": task.task_id, "heading": task.text, "answer_shape": task.answer_shape,
+                "body": body, "evidence_ids": used, "evidence_blocks": evidence_blocks,
+                "resolved": bool(used), "audience": task.audience,
+            }
+        )
+        deterministic.append(body if len(tasks) == 1 else f"### {index}. {task.text}\n\n{body}")
+    intents = {item.intent for item in tasks}
+    model_required = len(tasks) > 1 or "comparison" in intents or len(evidence) > 3
+    return {
+        "user_goal": user_goal, "active_topic": active_topic, "locale": locale,
+        "sections": sections, "unresolved_task_ids": unresolved,
+        "selected_runtime_skills": _selected_runtime_skills(tasks, context_used),
+        "prohibited_claims": [
+            "facts_not_present_in_evidence", "unexecuted_action_completion",
+            "private_implementation_details", "model_or_provider_identity",
+        ],
+        "required_style": ["conclusion_first", "specific", "polite", "resolve_to_next_step", "no_repeated_questions"],
+        "deterministic_answer": "\n\n".join(deterministic).strip(),
+        "evidence_ids": list(dict.fromkeys(all_used)), "model_required": model_required,
+    }
+
+
+def classify_processing_grade(tasks: list[QuestionTask], evidence: list[EvidenceItem], blueprint: dict[str, Any]) -> str:
+    if blueprint.get("unresolved_task_ids"):
+        return "L3_CONTEXT_REQUIRED"
+    if len(tasks) > 1:
+        return "L2_MULTI_TASK_COMPOSE"
+    if len(evidence) > 1 or tasks[0].intent in {"comparison", "troubleshooting", "procedure"}:
+        return "L1_STRUCTURED_COMPOSE"
+    return "L0_DETERMINISTIC_EXACT"
+
+
+class SupportRuntime:
+    def __init__(self, *, search: Callable[..., list[Any]], max_parallel_search: int = 4):
+        self.retriever = EvidenceRetriever(search, max_parallel=max_parallel_search)
+
+    async def prepare(
+        self, *, message: str, locale: str, source: str,
+        context: dict[str, Any], analysis: dict[str, Any]
+    ) -> PreparedSupport:
+        normalized = normalize_japanese(message)
+        tasks = decompose_questions(message=normalized, source=source, context=context, analysis=analysis)
+        user_goal = str(analysis.get("user_goal") or context.get("user_goal") or normalized)
+        active_topic = str(analysis.get("active_topic") or context.get("active_topic") or detect_subject(normalized))
+        dictionary = build_analysis_dictionary(message=normalized, context=context, analysis=analysis, tasks=tasks)
+        plans = plan_search(tasks, user_goal=user_goal, active_topic=active_topic)
+        fresh = await self.retriever.retrieve(plans)
+        evidence = _merge_evidence(fresh, _cached_evidence(context, tasks))
+        blueprint = build_blueprint(
+            tasks=tasks, evidence=evidence, user_goal=user_goal, active_topic=active_topic,
+            locale=locale, context_used=bool(context.get("user_goal") or context.get("turns")),
+        )
+        grade = classify_processing_grade(tasks, evidence, blueprint)
+        return PreparedSupport(
+            normalized_message=normalized, analysis_dictionary=dictionary,
+            tasks=tasks, search_tasks=plans, evidence=evidence, blueprint=blueprint,
+            processing_grade=grade, model_required=bool(blueprint.get("model_required")),
+        )
+
+
+def validate_response(
+    *, answer: str, prepared: PreparedSupport, answered_task_ids: Iterable[str],
+    unresolved_task_ids: Iterable[str], used_evidence_ids: Iterable[str],
+    external_violations: Iterable[str] = ()
+) -> ResponseValidation:
+    text = str(answer or "").strip()
+    answered = list(dict.fromkeys(str(value) for value in answered_task_ids if str(value)))
+    unresolved = list(dict.fromkeys(str(value) for value in unresolved_task_ids if str(value)))
+    used = list(dict.fromkeys(str(value) for value in used_evidence_ids if str(value)))
+    task_ids = {item.task_id for item in prepared.tasks}
+    evidence_ids = {item.evidence_id for item in prepared.evidence}
+    violations = list(external_violations)
+    if not text:
+        violations.append("empty_answer")
+    if not set(answered).issubset(task_ids) or not set(unresolved).issubset(task_ids):
+        violations.append("unknown_task_reference")
+    if task_ids.difference(answered).difference(unresolved):
+        violations.append("question_coverage_missing")
+    if not set(used).issubset(evidence_ids):
+        violations.append("unknown_evidence_reference")
+    if evidence_ids and answered and not used:
+        violations.append("evidence_grounding_missing")
+    if re.search(r"(?:情報がありません|回答できません|お問い合わせください|I (?:cannot|can't) answer)", text, re.I):
+        violations.append("generic_non_answer")
+    if re.search(r"(?:返金しました|削除しました|解約しました|処理しました|設定しました|refunded|deleted|cancelled)", text, re.I):
+        violations.append("unverified_action_claim")
+    if contains_internal_implementation(text):
+        violations.append("internal_implementation")
+    return ResponseValidation(
+        passed=not violations, violations=list(dict.fromkeys(violations)),
+        answered_task_ids=answered, unresolved_task_ids=unresolved, used_evidence_ids=used,
+    )
+
+
+class FeedbackStore:
+    """Stores anonymized review candidates; it never publishes to Notion automatically."""
+
+    def __init__(self, root: Path):
+        self.root = root / "feedback"
+        self.root.mkdir(parents=True, exist_ok=True)
+        self.index_path = self.root / "candidate-index.json"
+        self._lock = threading.Lock()
+
+    def record(
+        self, *, session_id: str, message: str, prepared: PreparedSupport,
+        validation: ResponseValidation, status: str
+    ) -> str | None:
+        safe_message = redact_text(normalize_japanese(message)).text[:1000]
+        safe_tasks = sanitize_structure([item.as_dict() for item in prepared.tasks])
+        safe_search_tasks = sanitize_structure([item.as_dict() for item in prepared.search_tasks])
+        safe_kb_ids = [redact_text(item.kb_id).text[:160] for item in prepared.evidence]
+        fingerprint_source = json.dumps(
+            {"message": safe_message, "tasks": safe_tasks, "kb_ids": sorted(safe_kb_ids)},
+            ensure_ascii=False, sort_keys=True,
+        )
+        fingerprint = hashlib.sha256(fingerprint_source.encode("utf-8")).hexdigest()
+        candidate_id = "qic_" + fingerprint[:24]
+        with self._lock:
+            index = self._read_index()
+            if fingerprint in index:
+                return None
+            gap_types: list[str] = []
+            if prepared.blueprint.get("unresolved_task_ids"):
+                gap_types.append("kb_content_gap")
+            if any(plan.query and not any(plan.task_id in item.task_ids for item in prepared.evidence) for plan in prepared.search_tasks):
+                gap_types.append("search_term_or_content_gap")
+            if validation.violations:
+                gap_types.append("answer_quality_gap")
+            row = {
+                "candidate_id": candidate_id, "fingerprint": fingerprint,
+                "created_at": datetime.now(UTC).isoformat(),
+                "session_hash": hashlib.sha256(session_id.encode("utf-8")).hexdigest()[:24],
+                "normalized_question": safe_message,
+                "question_tasks": safe_tasks, "search_tasks": safe_search_tasks,
+                "matched_kb_ids": sorted(safe_kb_ids),
+                "gap_types": list(dict.fromkeys(gap_types)), "status": status,
+                "validation_violations": sanitize_structure(validation.violations),
+                "approval_required": True, "auto_publish": False,
+            }
+            daily = self.root / (datetime.now(UTC).date().isoformat() + ".jsonl")
+            with daily.open("a", encoding="utf-8") as handle:
+                handle.write(json.dumps(row, ensure_ascii=False, sort_keys=True) + "\n")
+            index[fingerprint] = candidate_id
+            if len(index) > 10000:
+                index = dict(list(index.items())[-10000:])
+            temporary = self.index_path.with_suffix(".tmp")
+            temporary.write_text(json.dumps(index, ensure_ascii=False, sort_keys=True), encoding="utf-8")
+            temporary.replace(self.index_path)
+        return candidate_id
+
+    def _read_index(self) -> dict[str, str]:
+        if not self.index_path.exists():
+            return {}
+        try:
+            value = json.loads(self.index_path.read_text(encoding="utf-8"))
+            return value if isinstance(value, dict) else {}
+        except (OSError, json.JSONDecodeError):
+            return {}

runtime/v8.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import os
+import platform
+import shutil
+import subprocess
+import tarfile
+import time
+import urllib.request
+import uuid
+from pathlib import Path
+from typing import Any
+
+from .config import Settings
+from .schemas import NodeResponse
+
+
+class V8Unavailable(RuntimeError):
+    pass
+
+
+NODE_VERSION = "22.16.0"
+NODE_DISTRIBUTIONS = {
+    "x86_64": ("linux-x64", "f4cb75bb036f0d0eddf6b79d9596df1aaab9ddccd6a20bf489be5abe9467e84e"),
+    "amd64": ("linux-x64", "f4cb75bb036f0d0eddf6b79d9596df1aaab9ddccd6a20bf489be5abe9467e84e"),
+    "aarch64": ("linux-arm64", "eab80cb88f8fda1e65f5e8d0420c9809bdb320b03fd34976ab7161b6e703b910"),
+    "arm64": ("linux-arm64", "eab80cb88f8fda1e65f5e8d0420c9809bdb320b03fd34976ab7161b6e703b910"),
+}
+
+
+def _node_major(binary: str) -> int:
+    try:
+        version = subprocess.run([binary, "--version"], capture_output=True, text=True, timeout=5, check=True).stdout.strip()
+        return int(version.removeprefix("v").split(".")[0])
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return 0
+
+
+def _safe_socket_path(configured: Path) -> Path:
+    """Unix sockets have a short platform path limit; use a stable /tmp path when needed."""
+    encoded = os.fsencode(str(configured))
+    if len(encoded) <= 96:
+        return configured
+    digest = hashlib.sha256(encoded).hexdigest()[:20]
+    return Path("/tmp") / f"customer-ai-v8-{digest}.sock"
+
+
+class NodeBootstrap:
+    def __init__(self, settings: Settings):
+        self.settings = settings
+
+    def resolve(self) -> str:
+        if _node_major(self.settings.node_binary) >= 22:
+            return self.settings.node_binary
+        machine = platform.machine().lower()
+        if machine not in NODE_DISTRIBUTIONS:
+            raise V8Unavailable(f"unsupported Node.js platform: {machine}")
+        flavor, expected_sha = NODE_DISTRIBUTIONS[machine]
+        filename = f"node-v{NODE_VERSION}-{flavor}.tar.xz"
+        cache_dir = self.settings.data_root / "runtime" / "node"
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        archive = cache_dir / filename
+        if not archive.exists() or self._sha256(archive) != expected_sha:
+            temp_archive = archive.with_suffix(".download")
+            temp_archive.unlink(missing_ok=True)
+            url = f"https://nodejs.org/dist/v{NODE_VERSION}/{filename}"
+            with urllib.request.urlopen(url, timeout=120) as response, temp_archive.open("wb") as handle:
+                shutil.copyfileobj(response, handle)
+            if self._sha256(temp_archive) != expected_sha:
+                temp_archive.unlink(missing_ok=True)
+                raise V8Unavailable("downloaded Node.js archive checksum mismatch")
+            os.replace(temp_archive, archive)
+        local_root = Path("/tmp") / f"customer-ai-node-v{NODE_VERSION}-{flavor}"
+        binary = local_root / "bin" / "node"
+        if _node_major(str(binary)) >= 22:
+            return str(binary)
+        temp_root = local_root.with_name(local_root.name + f".tmp-{os.getpid()}")
+        shutil.rmtree(temp_root, ignore_errors=True)
+        temp_root.mkdir(parents=True, exist_ok=True)
+        with tarfile.open(archive, mode="r:xz") as package:
+            members = package.getmembers()
+            prefix = f"node-v{NODE_VERSION}-{flavor}/"
+            for member in members:
+                if not member.name.startswith(prefix) or ".." in Path(member.name).parts:
+                    raise V8Unavailable("unsafe Node.js archive path")
+            package.extractall(temp_root, filter="data")
+        extracted = temp_root / f"node-v{NODE_VERSION}-{flavor}"
+        shutil.rmtree(local_root, ignore_errors=True)
+        os.replace(extracted, local_root)
+        shutil.rmtree(temp_root, ignore_errors=True)
+        binary.chmod(0o755)
+        if _node_major(str(binary)) < 22:
+            raise V8Unavailable("bootstrapped Node.js runtime failed validation")
+        return str(binary)
+
+    @staticmethod
+    def _sha256(path: Path) -> str:
+        digest = hashlib.sha256()
+        with path.open("rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                digest.update(chunk)
+        return digest.hexdigest()
+
+
+class V8Supervisor:
+    def __init__(self, settings: Settings):
+        self.settings = settings
+        self.process: asyncio.subprocess.Process | None = None
+        self._lock = asyncio.Lock()
+        self.node_binary = settings.node_binary
+        self.socket_path = _safe_socket_path(settings.node_socket)
+
+    async def start(self) -> None:
+        async with self._lock:
+            if self.process and self.process.returncode is None:
+                return
+            if self.process is not None:
+                try:
+                    await self.process.wait()
+                except (ProcessLookupError, ChildProcessError):
+                    pass
+                self.process = None
+            self.node_binary = await asyncio.to_thread(NodeBootstrap(self.settings).resolve)
+            self.socket_path.unlink(missing_ok=True)
+            script = Path(__file__).resolve().parent.parent / "v8" / "server.mjs"
+            env = os.environ.copy()
+            env["CUSTOMER_AI_NODE_SOCKET"] = str(self.socket_path)
+            self.process = await asyncio.create_subprocess_exec(
+                self.node_binary,
+                f"--max-old-space-size={self.settings.node_memory_mb}",
+                str(script),
+                env=env,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            for _ in range(50):
+                if self.socket_path.exists():
+                    return
+                if self.process.returncode is not None:
+                    stderr = b""
+                    if self.process.stderr is not None:
+                        stderr = await self.process.stderr.read()
+                    message = stderr.decode("utf-8", errors="replace").strip()
+                    raise V8Unavailable(message or "Node V8 process exited before socket readiness")
+                await asyncio.sleep(0.1)
+            await self.stop()
+            raise V8Unavailable("Node V8 socket did not become ready")
+
+    async def stop(self) -> None:
+        process = self.process
+        self.process = None
+        try:
+            if process is None:
+                return
+            if process.returncode is None:
+                try:
+                    process.terminate()
+                except ProcessLookupError:
+                    pass
+                try:
+                    await asyncio.wait_for(process.wait(), timeout=5)
+                except TimeoutError:
+                    try:
+                        process.kill()
+                    except ProcessLookupError:
+                        pass
+                    try:
+                        await process.wait()
+                    except (ProcessLookupError, ChildProcessError):
+                        pass
+            else:
+                try:
+                    await process.wait()
+                except (ProcessLookupError, ChildProcessError):
+                    pass
+        finally:
+            self.socket_path.unlink(missing_ok=True)
+
+    async def request(self, phase: str, payload: dict[str, Any], *, timeout: float = 15.0) -> dict[str, Any]:
+        if not self.process or self.process.returncode is not None:
+            await self.start()
+        request_id = str(uuid.uuid4())
+        request = {
+            "request_id": request_id,
+            "phase": phase,
+            "deadline_at": int((time.time() + timeout) * 1000),
+            "payload": payload,
+        }
+        try:
+            reader, writer = await asyncio.open_unix_connection(str(self.socket_path))
+            writer.write((json.dumps(request, ensure_ascii=False) + "\n").encode())
+            await writer.drain()
+            raw = await asyncio.wait_for(reader.readline(), timeout=timeout)
+            writer.close()
+            await writer.wait_closed()
+            response = NodeResponse.model_validate_json(raw)
+            if not response.ok:
+                raise V8Unavailable(response.error_code or "node_error")
+            return response.result
+        except (ConnectionError, OSError, TimeoutError, ValueError) as exc:
+            await self.stop()
+            raise V8Unavailable(str(exc)) from exc

scripts/provision_hf.py

@@ -0,0 +1,215 @@
+# /// script
+# requires-python = ">=3.11"
+# dependencies = ["huggingface_hub>=1.24.0", "httpx>=0.28,<1"]
+# ///
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+
+import httpx
+from huggingface_hub import HfApi, Volume
+
+# Deployment preserves existing HF runtime secrets when GitHub values are absent.
+ROOT = Path(__file__).resolve().parents[1]
+TOKEN = os.environ.get("HF_TOKEN", "")
+NAMESPACE = os.environ.get("HF_NAMESPACE", "G-ACE")
+SPACE_NAME = os.environ.get("HF_SPACE_NAME", "astera-customerAI")
+BUCKET_NAME = os.environ.get("HF_BUCKET_NAME", "astera-customerai-data")
+SPACE_ID = f"{NAMESPACE}/{SPACE_NAME}"
+BUCKET_ID = f"{NAMESPACE}/{BUCKET_NAME}"
+MODEL_REVISION = os.environ.get(
+    "CUSTOMER_AI_MODEL_REVISION",
+    "cdbee75f17c01a7cc42f958dc650907174af0554",
+)
+
+RUNTIME_SECRETS = (
+    "CUSTOMER_AI_HMAC_SECRET",
+    "INTERNAL_EVENT_API_URL",
+    "INTERNAL_EVENT_API_TOKEN",
+    "NOTION_TOKEN",
+    "NOTION_DATA_SOURCE_ID",
+)
+
+
+def runtime_environment() -> dict[str, str]:
+    if not TOKEN:
+        raise SystemExit("HF_TOKEN_MISSING")
+
+    values: dict[str, str] = {}
+    missing: list[str] = []
+    for name in RUNTIME_SECRETS:
+        value = os.environ.get(name, "").strip()
+        if value:
+            values[name] = value
+        else:
+            missing.append(name)
+
+    if missing:
+        # upload_folder and Space configuration do not delete existing HF secrets.
+        # Missing GitHub secrets are therefore left untouched so an existing Space
+        # can retain its current runtime credentials during a code-only deployment.
+        print("HF_RUNTIME_SECRETS_PRESERVED=" + ",".join(missing))
+    return values
+
+
+def verify_bucket(api: HfApi) -> None:
+    payload = json.dumps(
+        {
+            "github_sha": os.environ.get("GITHUB_SHA", "manual"),
+            "verified_at": time.time(),
+        },
+        sort_keys=True,
+    ).encode("utf-8")
+    probe_path = f"runtime-verification/deploy-{os.environ.get('GITHUB_RUN_ID', 'manual')}.json"
+    with tempfile.TemporaryDirectory(prefix="hf-customer-ai-") as temporary:
+        downloaded = Path(temporary) / "probe.json"
+        try:
+            api.batch_bucket_files(BUCKET_ID, add=[(payload, probe_path)])
+            api.download_bucket_files(BUCKET_ID, files=[(probe_path, str(downloaded))])
+            if downloaded.read_bytes() != payload:
+                raise RuntimeError("HF_BUCKET_READ_AFTER_WRITE_MISMATCH")
+            print("HF_BUCKET_WRITE_READ_OK")
+        finally:
+            api.batch_bucket_files(BUCKET_ID, delete=[probe_path])
+            print("HF_BUCKET_PROBE_REMOVED")
+
+
+def wait_for_space(api: HfApi) -> None:
+    last = ""
+    headers = {"Authorization": f"Bearer {TOKEN}"}
+    for attempt in range(30):
+        info = api.space_info(
+            SPACE_ID,
+            expand=["runtime", "private", "sha", "sdk", "subdomain"],
+        )
+        if not info.private:
+            raise RuntimeError("HF_SPACE_NOT_PRIVATE")
+        if info.subdomain:
+            health_url = f"https://{info.subdomain}.hf.space/healthz"
+            ready_url = f"https://{info.subdomain}.hf.space/readyz"
+            try:
+                response = httpx.get(
+                    health_url,
+                    headers=headers,
+                    timeout=30,
+                    follow_redirects=True,
+                )
+                last = f"{response.status_code}:{response.text[:300]}"
+                if response.status_code == 200 and response.json().get("status") == "ok":
+                    print("HF_SPACE_HEALTH_OK")
+                    ready = httpx.get(
+                        ready_url,
+                        headers=headers,
+                        timeout=30,
+                        follow_redirects=True,
+                    )
+                    print(f"HF_SPACE_READY_STATUS={ready.status_code}")
+                    print(ready.text[:2000])
+                    print("HF_PRIVATE_RUNTIME_DEPLOYED")
+                    return
+            except Exception as error:  # build and cold-start transition
+                last = repr(error)
+        if attempt == 29:
+            break
+        time.sleep(20)
+    raise RuntimeError(f"HF_SPACE_HEALTH_TIMEOUT:{last}")
+
+
+def main() -> None:
+    runtime_secrets = runtime_environment()
+    api = HfApi(token=TOKEN)
+    identity = api.whoami()
+    print(f"HF_AUTHENTICATED_AS={identity.get('name') or identity.get('fullname')}")
+
+    bucket = api.create_bucket(BUCKET_ID, private=True, exist_ok=True)
+    if not bucket:
+        raise RuntimeError("HF_BUCKET_CREATE_FAILED")
+    print(f"HF_PRIVATE_BUCKET_READY={BUCKET_ID}")
+
+    volume = Volume(
+        type="bucket",
+        source=BUCKET_ID,
+        mount_path="/data/customer-ai",
+        read_only=False,
+    )
+    api.create_repo(
+        repo_id=SPACE_ID,
+        repo_type="space",
+        private=True,
+        exist_ok=True,
+        space_sdk="gradio",
+        space_volumes=[volume],
+    )
+    api.update_repo_settings(repo_id=SPACE_ID, repo_type="space", private=True)
+    api.set_space_volumes(SPACE_ID, volumes=[volume])
+    print(f"HF_PRIVATE_SPACE_READY={SPACE_ID}")
+    print("HF_BUCKET_MOUNT=/data/customer-ai")
+
+    for key, value in runtime_secrets.items():
+        api.add_space_secret(SPACE_ID, key=key, value=value)
+
+    variables = {
+        "CUSTOMER_AI_DATA_ROOT": "/data/customer-ai",
+        "CUSTOMER_AI_MODEL_ID": os.environ.get(
+            "CUSTOMER_AI_MODEL_ID", "Qwen/Qwen3-4B-Instruct-2507"
+        ),
+        "CUSTOMER_AI_MODEL_REVISION": MODEL_REVISION,
+        "CUSTOMER_AI_ENABLE_MODEL": os.environ.get("CUSTOMER_AI_ENABLE_MODEL", "0"),
+        "CUSTOMER_AI_GPU_DAILY_BUDGET_SECONDS": "2100",
+        "CUSTOMER_AI_NODE_BINARY": "node",
+        "CUSTOMER_AI_NODE_SOCKET": "/tmp/customer-ai-v8.sock",
+        "CUSTOMER_AI_NODE_MEMORY_MB": "384",
+        "CUSTOMER_AI_SESSION_CACHE_TTL_SECONDS": "1800",
+        "CUSTOMER_AI_SESSION_CACHE_MAX_SESSIONS": "256",
+        "CUSTOMER_AI_SESSION_CACHE_MAX_TURNS": "12",
+        "CUSTOMER_AI_KB_CACHE_TTL_SECONDS": "120",
+        "CUSTOMER_AI_KB_CACHE_MAX_ENTRIES": "256",
+        "INTERNAL_EVENT_SOURCE_ID": os.environ.get(
+            "INTERNAL_EVENT_SOURCE_ID", "hf-private-runtime"
+        ),
+        "INTERNAL_EVENT_RESULT_DESTINATION_ID": os.environ.get(
+            "INTERNAL_EVENT_RESULT_DESTINATION_ID", "app-receiver"
+        ),
+        "DEPLOYED_GITHUB_COMMIT": os.environ.get("GITHUB_SHA", "manual"),
+    }
+    for key, value in variables.items():
+        api.add_space_variable(SPACE_ID, key=key, value=value)
+    print(f"HF_SPACE_SECRETS_CONFIGURED={len(runtime_secrets)}")
+    print(f"HF_SPACE_VARIABLES_CONFIGURED={len(variables)}")
+
+    api.upload_folder(
+        repo_id=SPACE_ID,
+        repo_type="space",
+        folder_path=str(ROOT),
+        commit_message=os.environ.get(
+            "HF_COMMIT_MESSAGE", "Deploy Customer AI from GitHub main"
+        ),
+        ignore_patterns=[
+            ".git/**",
+            ".github/**",
+            ".pytest_cache/**",
+            ".pytest-*/**",
+            ".ruff_cache/**",
+            "__pycache__/**",
+            "*.pyc",
+            ".env",
+            "docs/**",
+            "tests/**",
+            "edge/**",
+            "test-results/**",
+            "state.md",
+        ],
+    )
+    api.restart_space(SPACE_ID)
+    print("HF_SPACE_UPLOAD_COMPLETE")
+
+    verify_bucket(api)
+    wait_for_space(api)
+
+
+if __name__ == "__main__":
+    main()

scripts/review.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+REVIEWS = {
+    "conversation": {
+        "prompt": "Review whether first answers and multiple follow-up turns preserve the same user goal, active topic, confirmed details, answered and unresolved questions, recent turns, evidence, and the last answer blueprint.",
+        "checks": [
+            "ConversationCache",
+            "user_goal",
+            "active_topic",
+            "unresolved_questions",
+            "answered_question_ids",
+            "question_ledger",
+            "evidence_cache",
+            "last_blueprint",
+            "context_used",
+        ],
+    },
+    "support_preparation": {
+        "prompt": "Review whether documents are normalized, decomposed into question tasks, converted into bounded search tasks, bound to verified KB evidence, and assembled into a support blueprint before any language-model call.",
+        "checks": [
+            "normalize_japanese",
+            "QuestionTask",
+            "SearchTask",
+            "EvidenceRetriever",
+            "analysis_dictionary",
+            "build_blueprint",
+            "processing_grade",
+            "support_packet",
+        ],
+    },
+    "engine_boundary": {
+        "prompt": "Review whether the lightweight model is optional, receives only a prepared support packet, cannot own facts/routing/actions/completion, and is limited to one initial call plus at most one violation-targeted repair.",
+        "checks": [
+            "ConversationLanguageEngine",
+            "answer_only_from_supplied_evidence",
+            "repair_limit",
+            "repair_attempted",
+            "model_required",
+            "deterministic_answer",
+        ],
+    },
+    "security_and_feedback": {
+        "prompt": "Review PII and secret redaction, internal implementation leakage, task/evidence coverage, unverified action claims, and anonymized deduplicated KB feedback candidates that require approval and never auto-publish.",
+        "checks": [
+            "verify_hmac",
+            "redact_text",
+            "sanitize_structure",
+            "unknown_evidence_reference",
+            "question_coverage_missing",
+            "unverified_action_claim",
+            "FeedbackStore",
+            "approval_required",
+            "auto_publish",
+        ],
+    },
+}
+
+FORBIDDEN_RUNTIME_PATTERNS = {
+    "kagura-engine.js": "Astera/Kagura engine must not be invoked",
+    "CUSTOMER_AI_ASTERA_": "Astera engine runtime variables must not exist",
+    "class AsteraBootstrap": "Astera engine bootstrap must not exist",
+    "class SkillRegistry": "a generic all-purpose skill registry is not the dedicated Customer AI runtime",
+    "class RoutineBotSupervisor": "multiple generic routine bots are outside the focused maintenance design",
+    "class WorkerPool": "an unbounded generic worker pool is unnecessary",
+    "auto_publish\": True": "user questions must never auto-publish to the approved KB",
+}
+
+
+def collect_text() -> str:
+    return "\n".join(
+        path.read_text(encoding="utf-8")
+        for path in ROOT.rglob("*")
+        if path.is_file() and path.suffix in {".py", ".mjs", ".md", ".txt", ".toml", ".example"}
+    )
+
+
+def check_python_syntax() -> list[str]:
+    errors = []
+    for path in ROOT.rglob("*.py"):
+        try:
+            ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        except SyntaxError as exc:
+            errors.append(f"{path}: {exc}")
+    return errors
+
+
+def check_forbidden_runtime() -> list[str]:
+    errors: list[str] = []
+    runtime_paths = [ROOT / "runtime", ROOT / "v8", ROOT / ".env.example", ROOT / "scripts" / "provision_hf.py"]
+    for base in runtime_paths:
+        paths = [base] if base.is_file() else list(base.rglob("*")) if base.exists() else []
+        for path in paths:
+            if not path.is_file() or path.suffix not in {".py", ".mjs", ".md", ".example"}:
+                continue
+            text = path.read_text(encoding="utf-8")
+            for pattern, reason in FORBIDDEN_RUNTIME_PATTERNS.items():
+                if pattern in text:
+                    errors.append(f"{path.relative_to(ROOT)}: {reason}: {pattern}")
+    return errors
+
+
+def run_review(name: str, text: str) -> dict:
+    spec = REVIEWS[name]
+    missing = [item for item in spec["checks"] if item.lower() not in text.lower()]
+    return {"name": name, "prompt": spec["prompt"], "passed": not missing, "missing": missing}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--all", action="store_true")
+    parser.add_argument("--review", choices=REVIEWS)
+    args = parser.parse_args()
+    text = collect_text()
+    names = list(REVIEWS) if args.all or not args.review else [args.review]
+    results = [run_review(name, text) for name in names]
+    syntax = check_python_syntax()
+    forbidden = check_forbidden_runtime()
+    output = {"reviews": results, "python_syntax_errors": syntax, "forbidden_runtime_errors": forbidden}
+    print(json.dumps(output, ensure_ascii=False, indent=2))
+    return 0 if all(item["passed"] for item in results) and not syntax and not forbidden else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

templates/customer-ai-kb-template.json

@@ -0,0 +1,119 @@
+{
+  "template_version": "1.0",
+  "purpose": "Astera Customer AIが一次質問、追加質問、比較、手順、障害対応まで回答するためのKBレコード作成テンプレート",
+  "rules": {
+    "one_record_one_answer_scope": "1レコードは1つの主質問と、その質問から自然に派生する追加質問の範囲に限定する",
+    "facts_only": "実装済みまたは文書確認済みの事実だけを書く。予定、推測、未確認情報を公開しない",
+    "body_generation": "本文を空にした場合、目的・理由・前提条件・手順・条件・例外・障害・完了確認・追加質問からRuntimeが本文を構成する",
+    "publish_gate": "公開状態=公開、実装状態=実装済みまたは文書確認済み、要再確認=false のレコードだけがRuntime KBへ入る",
+    "answer_boundary": "アカウント固有状態、決済結果、実行結果などKBだけで断定できない範囲を明記する",
+    "evidence": "根拠Pathまたは根拠URLと確認日を必ず保持する。公開回答へ内部Pathを直接出さない"
+  },
+  "required_fields": [
+    "id",
+    "製品",
+    "カテゴリ",
+    "質問種別",
+    "質問",
+    "短い回答",
+    "対象",
+    "検索語",
+    "回答境界",
+    "公開状態",
+    "実装状態",
+    "要再確認",
+    "確認日"
+  ],
+  "pages": [
+    {
+      "id": "product-category-topic-001",
+      "製品": "Astera | Astera-app | Webhook Gateway | その他の対象製品",
+      "システム": "対象となるSystemまたは機能名",
+      "カテゴリ": "概要 | 導入 | 利用方法 | 仕様 | 料金 | 契約 | API | 障害 | 運用 | セキュリティ | 法人・支援",
+      "質問種別": "definition | availability | procedure | comparison | pricing | contract | troubleshooting | limitation",
+      "質問": "利用者が実際に尋ねる代表質問を1文で記入",
+      "短い回答": "最初に返す結論を、条件を含めて具体的に記入",
+      "本文": "",
+      "目的": [
+        "この回答で利用者が理解または完了できる状態"
+      ],
+      "理由": [
+        "なぜその回答になるのか",
+        "設計・仕様・運用上の根拠"
+      ],
+      "前提条件": [
+        "回答が成立する利用者状態、プラン、画面、機能、実装状態"
+      ],
+      "対象": [
+        "一般利用者",
+        "開発者",
+        "法人",
+        "投資家・スポンサー"
+      ],
+      "利用条件": [
+        "利用可能な条件",
+        "必要な登録・権限・環境"
+      ],
+      "手順": [
+        "最初に行う操作",
+        "次に行う操作",
+        "最後に確認する内容"
+      ],
+      "条件": [
+        "通常ケースで変わる条件"
+      ],
+      "例外": [
+        "通常手順が当てはまらないケース",
+        "例外時の正しい扱い"
+      ],
+      "障害症状": [
+        "利用者が目にする症状、表示、エラー、未反映状態"
+      ],
+      "原因": [
+        "確認済みの原因候補。推測は書かない"
+      ],
+      "確認方法": [
+        "原因を切り分ける確認順序"
+      ],
+      "解決手順": [
+        "解決のための具体的な操作順序"
+      ],
+      "完了確認": [
+        "解決または設定完了を判断する基準"
+      ],
+      "追加質問": [
+        "この回答の後に聞かれやすい質問",
+        "省略表現や口語での聞かれ方",
+        "前の回答を前提にした追加質問"
+      ],
+      "検索語": "製品名 機能名 正式用語 口語 誤表記 症状 手順",
+      "同義語": [
+        "表記揺れ",
+        "略称",
+        "利用者が使う別の言い方"
+      ],
+      "回答境界": [
+        "KBだけで断定できる範囲",
+        "アカウント・決済・実処理の正本確認が必要な範囲"
+      ],
+      "禁止回答": [
+        "未実装機能を利用可能と書かない",
+        "実行していない操作を完了と書かない",
+        "未確定料金や契約条件を作らない",
+        "非公開の内部実装・Secret・個人情報を出さない"
+      ],
+      "関連KB": [
+        "関連するKB ID"
+      ],
+      "根拠Path": [
+        "GitHub上の根拠ファイルPathまたはNotion正本の参照位置"
+      ],
+      "根拠種別": "実装Code | 公開仕様 | 利用規約 | 運用手順 | 確認済み文書",
+      "公開状態": "下書き",
+      "実装状態": "未確認",
+      "要再確認": true,
+      "確認日": "YYYY-MM-DD",
+      "url": "根拠URLまたはNotionページURL"
+    }
+  ]
+}

v8/server.mjs

@@ -0,0 +1,283 @@
+import net from "node:net";
+import fs from "node:fs";
+
+const socketPath = process.env.CUSTOMER_AI_NODE_SOCKET || "/tmp/customer-ai-v8.sock";
+try { fs.unlinkSync(socketPath); } catch (error) { if (error.code !== "ENOENT") throw error; }
+
+const TOPICS = [
+  ["credit", /クレジット|残高|credit|付与|反映/i],
+  ["account", /アカウント|ログイン|パスワード|認証|account|login|退会|解約/i],
+  ["billing", /料金|支払|決済|プラン|請求|billing|payment|price/i],
+  ["webhook-gateway", /webhook|配送|再送|リプレイ|届か/i],
+  ["astera-app", /astera[- ]?app|アステラアプリ/i],
+  ["astera", /astera|アステラ/i],
+  ["api", /api|キー|key|エンドポイント|連携/i],
+  ["corporate", /法人|スポンサー|投資|提携|enterprise|sponsor/i],
+];
+
+const INTENTS = [
+  ["comparison", /違い|比較|どちら|何が異なる|\bvs\b/i],
+  ["troubleshooting", /エラー|動かない|できない|反映されない|届かない|失敗|不具合|直し/i],
+  ["procedure", /方法|手順|どうやって|どこから|どこを|何を確認|確認すれば|確認方法|設定|使い方|始め方|導入/i],
+  ["pricing", /料金|価格|いくら|費用|課金|クレジット/i],
+  ["contract", /契約|解約|退会|返金|更新|支払/i],
+  ["availability", /使える|使えます|使えない|利用でき|対応|可能|できる|未実装|提供/i],
+  ["limitation", /制限|上限|できない|禁止|対象外|条件/i],
+  ["definition", /とは|何ですか|何なの|意味|概要/i],
+];
+
+const EVIDENCE_BY_INTENT = {
+  comparison: ["definition", "responsibility", "limitations"],
+  troubleshooting: ["symptom", "cause", "check", "resolution", "completion_check"],
+  procedure: ["prerequisites", "ordered_steps", "completion_check"],
+  pricing: ["current_price", "conditions", "effective_date"],
+  contract: ["current_terms", "conditions", "ordered_steps"],
+  availability: ["implementation_status", "conditions", "limitations"],
+  limitation: ["answer_boundary", "conditions", "exceptions"],
+  definition: ["definition", "purpose", "scope"],
+  general: ["confirmed_answer", "conditions"],
+};
+
+const SHAPE_BY_INTENT = {
+  comparison: "comparison",
+  troubleshooting: "resolution_steps",
+  procedure: "ordered_steps",
+  pricing: "current_fact",
+  contract: "conditions_and_steps",
+  availability: "yes_no_with_conditions",
+  limitation: "boundary",
+  definition: "conclusion_and_detail",
+  general: "conclusion_and_detail",
+};
+
+const STOP_WORDS = new Set([
+  "これ", "それ", "その", "この", "あれ", "あと", "また", "さらに", "について", "教えて", "ください",
+  "です", "ます", "したい", "できる", "できます", "どう", "どこ", "何", "なぜ", "場合", "もの", "こと",
+]);
+
+function normalize(text) {
+  return String(text || "")
+    .normalize("NFKC")
+    .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "")
+    .replace(/[\t ]+/g, " ")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+function detectTopic(message) {
+  for (const [topic, pattern] of TOPICS) if (pattern.test(message)) return topic;
+  return "";
+}
+
+function detectIntent(message) {
+  for (const [intent, pattern] of INTENTS) if (pattern.test(message)) return intent;
+  return "general";
+}
+
+function detectAudience(message, source) {
+  if (/開発者|実装|コード|sdk|api|webhook|json|http|github/i.test(message)) return "developer";
+  if (/法人|企業|スポンサー|投資|提携/i.test(message)) return "business";
+  return source === "astera-app" ? "registered_user" : "general_user";
+}
+
+function extractDetails(message) {
+  const details = {};
+  const hour = message.match(/(?:午前|午後)?\s*(\d{1,2})\s*時/);
+  if (hour) details.approximate_hour = Number(hour[1]);
+  const errorCode = message.match(/(?:エラー|error)\s*[:：#-]?\s*([A-Z0-9_-]{3,40})/i);
+  if (errorCode) details.error_code = errorCode[1];
+  const timing = message.match(/今日|昨日|一昨日|今朝|昨夜|さっき|先ほど/);
+  if (timing) details.relative_time = timing[0];
+  return details;
+}
+
+function splitDocument(message) {
+  const lines = normalize(message)
+    .split(/\n+/)
+    .map((line) => line.replace(/^\s*(?:[-*・]|\d+[.)．、]|[①-⑳])\s*/, "").trim())
+    .filter(Boolean);
+  const source = lines.length ? lines : [normalize(message)];
+  const candidates = [];
+  for (const line of source) {
+    const sentences = line.split(/(?<=[?？!！。])\s*/).filter(Boolean);
+    for (const sentence of sentences) {
+      for (const part of sentence.split(/\s*(?:それと|さらに|加えて|あと、|また、)\s*/)) {
+        const raw = part.trim();
+        if (!raw) continue;
+        const questionMark = /[?？]$/.test(raw);
+        const cleaned = raw.replace(/[。?？\s]+$/g, "").trim();
+        if (!cleaned) continue;
+        const actionable = questionMark || detectIntent(cleaned) !== "general" || /教えて|知りたい|確認したい/.test(cleaned);
+        candidates.push({ text: cleaned, actionable });
+      }
+    }
+  }
+  const actionable = candidates.filter((item) => item.actionable).map((item) => item.text);
+  const selected = actionable.length ? actionable : candidates.map((item) => item.text);
+  return [...new Set(selected)].slice(0, 8).length ? [...new Set(selected)].slice(0, 8) : [normalize(message)];
+}
+
+function searchTerms(text, subject, intent, activeTopic) {
+  const working = normalize(text)
+    .replace(/(?:について|という|できますか|できるか|教えてください|教えて|とは|何ですか|どうですか)/g, " ")
+    .replace(/[?？!！。、,/:：()（）[\]「」『』-]+/g, " ")
+    .replace(/(?:は|が|を|に|で|と|や|へ|から|まで|より|の)/g, " ");
+  const candidates = working.match(/[A-Za-z][A-Za-z0-9_.-]{1,40}|[一-龯ぁ-んァ-ヶー]{2,24}/g) || [];
+  const seeded = [subject, activeTopic, intent, ...candidates];
+  const result = [];
+  for (const raw of seeded) {
+    const value = normalize(raw).toLowerCase();
+    if (!value || value === "general" || STOP_WORDS.has(value) || result.includes(value)) continue;
+    result.push(value);
+  }
+  return result.slice(0, 12);
+}
+
+function questionTasks(message, context, source, activeTopic) {
+  const previousTopic = context.active_topic || activeTopic || "";
+  return splitDocument(message).map((text, index) => {
+    const subject = detectTopic(text) || previousTopic || "general";
+    const intent = detectIntent(text);
+    return {
+      task_id: `q${index + 1}`,
+      text,
+      subject,
+      intent,
+      audience: detectAudience(text, source),
+      answer_shape: SHAPE_BY_INTENT[intent] || SHAPE_BY_INTENT.general,
+      search_terms: searchTerms(text, subject, intent, activeTopic),
+      required_evidence: EVIDENCE_BY_INTENT[intent] || EVIDENCE_BY_INTENT.general,
+      depends_on: [],
+    };
+  });
+}
+
+function analyzeTurn(payload) {
+  const message = normalize(payload.message);
+  const context = payload.context || {};
+  const source = payload.source || "astera-hp";
+  const explicitTopic = detectTopic(message);
+  const followUp = /^(それ|その|これ|では|じゃあ|あと|他|ちなみに|で、|なぜ|何で|どう|いつ|どこ|さっき|先ほど)/.test(message)
+    || (!explicitTopic && Boolean(context.active_topic || context.user_goal));
+  const activeTopic = explicitTopic || context.active_topic || "general";
+  const newTopic = Boolean(explicitTopic && context.active_topic && explicitTopic !== context.active_topic && !followUp);
+  const userGoal = newTopic || !context.user_goal ? message : context.user_goal;
+  const unresolved = Array.isArray(context.unresolved_questions) ? context.unresolved_questions.slice(-5) : [];
+  const tasks = questionTasks(message, context, source, activeTopic);
+  const retrievalParts = tasks.flatMap((task) => task.search_terms);
+  if (followUp && userGoal && userGoal !== message) retrievalParts.push(userGoal);
+  if (activeTopic && activeTopic !== "general") retrievalParts.push(activeTopic);
+  retrievalParts.push(...unresolved);
+  const retrievalQuery = [...new Set(retrievalParts.map(normalize).filter(Boolean))].join(" ").slice(0, 1200);
+  const conditions = { ...(context.confirmed_details || {}), ...extractDetails(message) };
+  return {
+    message,
+    follow_up: followUp,
+    context_used: Boolean(context.user_goal || (context.turns || []).length),
+    explicit_topic: explicitTopic,
+    active_topic: activeTopic,
+    user_goal: userGoal,
+    new_topic: newTopic,
+    confirmed_details: conditions,
+    retrieval_query: retrievalQuery,
+    question_count: tasks.length,
+    question_tasks: tasks,
+    analysis_dictionary: {
+      purpose: userGoal,
+      targets: [...new Set(tasks.map((task) => task.subject))],
+      conditions,
+      constraints: [
+        "use_confirmed_kb_only_for_product_facts",
+        "do_not_claim_unexecuted_actions",
+        "answer_every_detected_question_or_mark_it_unresolved",
+      ],
+      missing_information: [],
+      premises: Object.keys(context.confirmed_details || {}),
+      uncertainty: [],
+    },
+  };
+}
+
+function verifyTurn(payload) {
+  const answer = normalize(payload.answer);
+  const violations = [];
+  const availableEvidenceIds = new Set(payload.available_evidence_ids || []);
+  const questionTaskIds = new Set(payload.question_task_ids || []);
+  const answeredTaskIds = new Set(payload.answered_task_ids || []);
+  const unresolvedTaskIds = new Set(payload.unresolved_task_ids || []);
+  const usedEvidenceIds = new Set(payload.used_evidence_ids || []);
+
+  if (!answer) violations.push("empty_answer");
+  for (const evidenceId of usedEvidenceIds) {
+    if (!availableEvidenceIds.has(evidenceId)) violations.push("unknown_evidence_reference");
+  }
+  for (const taskId of [...answeredTaskIds, ...unresolvedTaskIds]) {
+    if (!questionTaskIds.has(taskId)) violations.push("unknown_task_reference");
+  }
+  for (const taskId of questionTaskIds) {
+    if (!answeredTaskIds.has(taskId) && !unresolvedTaskIds.has(taskId)) violations.push("question_coverage_missing");
+  }
+  if (availableEvidenceIds.size && answeredTaskIds.size && !usedEvidenceIds.size) violations.push("evidence_grounding_missing");
+  if (/情報がありません|回答できません|お問い合わせください|I (?:cannot|can't) answer/i.test(answer)) violations.push("generic_non_answer");
+  if (/\b(?:as an ai|as a language model|qwen|hugging face|model provider)\b/i.test(answer)) violations.push("engine_identity");
+  if (/(?:\/internal\/|src\/(?:system|component|feature|part)\/|\.env\b)/i.test(answer)) violations.push("internal_implementation");
+  if (/(?:返金しました|削除しました|解約しました|処理しました|設定しました|refunded|deleted|cancelled)/i.test(answer)) violations.push("unverified_action_claim");
+  const expectedTopic = payload.analysis?.active_topic || "";
+  const returnedTopic = payload.returned_topic || expectedTopic;
+  if (payload.analysis?.follow_up && expectedTopic && returnedTopic && expectedTopic !== returnedTopic) violations.push("conversation_topic_drift");
+  return {
+    answer,
+    passed: violations.length === 0,
+    violations: [...new Set(violations)],
+    coverage: {
+      question_task_ids: [...questionTaskIds],
+      answered_task_ids: [...answeredTaskIds],
+      unresolved_task_ids: [...unresolvedTaskIds],
+      used_evidence_ids: [...usedEvidenceIds],
+    },
+  };
+}
+
+async function handle(request) {
+  const started = Date.now();
+  const { request_id: requestId, phase, payload, deadline_at: deadlineAt } = request;
+  if (!requestId || !phase || payload === undefined) throw new Error("invalid_request");
+  if (Number(deadlineAt || 0) < Date.now()) throw new Error("deadline_exceeded");
+  let result;
+  if (phase === "analyze_turn") result = analyzeTurn(payload);
+  else if (phase === "verify_turn") result = verifyTurn(payload);
+  else if (phase === "ping") result = { pong: true, node: process.version };
+  else throw new Error("unsupported_phase");
+  return { request_id: requestId, ok: true, result, error_code: null, duration_ms: Date.now() - started };
+}
+
+const server = net.createServer((connection) => {
+  let buffer = "";
+  connection.setEncoding("utf8");
+  connection.on("data", async (chunk) => {
+    buffer += chunk;
+    if (buffer.length > 1_000_000) {
+      connection.destroy(new Error("request_too_large"));
+      return;
+    }
+    const newline = buffer.indexOf("\n");
+    if (newline < 0) return;
+    const raw = buffer.slice(0, newline);
+    buffer = buffer.slice(newline + 1);
+    try {
+      connection.end(JSON.stringify(await handle(JSON.parse(raw))) + "\n");
+    } catch (error) {
+      const requestId = (() => { try { return JSON.parse(raw).request_id || "unknown"; } catch { return "unknown"; } })();
+      connection.end(JSON.stringify({ request_id: requestId, ok: false, result: {}, error_code: String(error?.message || error), duration_ms: 0 }) + "\n");
+    }
+  });
+});
+
+server.listen(socketPath, () => fs.chmodSync(socketPath, 0o600));
+
+function shutdown() {
+  server.close();
+  try { fs.unlinkSync(socketPath); } catch {}
+  process.exit(0);
+}
+for (const signal of ["SIGINT", "SIGTERM"]) process.on(signal, shutdown);

v8/test/server.test.mjs

@@ -0,0 +1,119 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import net from "node:net";
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(here, "../..");
+const socket = `/tmp/customer-ai-test-${process.pid}.sock`;
+let child;
+
+test.before(async () => {
+  child = spawn(process.execPath, [path.join(root, "v8/server.mjs")], { env: { ...process.env, CUSTOMER_AI_NODE_SOCKET: socket } });
+  for (let index = 0; index < 100 && !fs.existsSync(socket); index += 1) await new Promise((resolve) => setTimeout(resolve, 20));
+  assert.equal(fs.existsSync(socket), true);
+});
+
+test.after(() => {
+  child?.kill("SIGTERM");
+  try { fs.unlinkSync(socket); } catch {}
+});
+
+function request(phase, payload) {
+  return new Promise((resolve, reject) => {
+    const client = net.createConnection(socket);
+    let data = "";
+    client.on("connect", () => client.write(JSON.stringify({ request_id: "req-1", phase, deadline_at: Date.now() + 5000, payload }) + "\n"));
+    client.on("data", (chunk) => { data += chunk; });
+    client.on("end", () => resolve(JSON.parse(data)));
+    client.on("error", reject);
+  });
+}
+
+test("follow-up analysis reuses cached goal and topic", async () => {
+  const response = await request("analyze_turn", {
+    message: "昨日の夜です。どこを確認すればいい？",
+    source: "astera-app",
+    context: {
+      user_goal: "購入したクレジットが反映されない問題を解決する",
+      active_topic: "credit",
+      confirmed_details: {},
+      unresolved_questions: [],
+      turns: [{ role: "user", text: "購入したクレジットが反映されません" }],
+    },
+  });
+  assert.equal(response.ok, true);
+  assert.equal(response.result.follow_up, true);
+  assert.equal(response.result.context_used, true);
+  assert.equal(response.result.active_topic, "credit");
+  assert.match(response.result.retrieval_query, /credit/);
+  assert.equal(response.result.confirmed_details.relative_time, "昨日");
+  assert.ok(response.result.question_tasks.some((item) => item.intent === "procedure"));
+  assert.equal(response.result.question_tasks.some((item) => item.text === "昨日の夜です"), false);
+});
+
+test("document analysis decomposes multiple questions into search tasks", async () => {
+  const response = await request("analyze_turn", {
+    message: "Asteraとは何ですか？Webhook Gatewayとの違いは？APIなしでも使えますか？",
+    source: "astera-hp",
+    context: { user_goal: "", active_topic: "", confirmed_details: {}, turns: [] },
+  });
+  assert.equal(response.ok, true);
+  assert.equal(response.result.question_count, 3);
+  assert.deepEqual(response.result.question_tasks.map((item) => item.task_id), ["q1", "q2", "q3"]);
+  assert.equal(response.result.question_tasks[0].intent, "definition");
+  assert.equal(response.result.question_tasks[1].intent, "comparison");
+  assert.equal(response.result.question_tasks[2].intent, "availability");
+  assert.ok(response.result.question_tasks[1].required_evidence.includes("responsibility"));
+  assert.ok(response.result.analysis_dictionary.targets.includes("astera"));
+});
+
+test("new explicit topic can replace the previous topic", async () => {
+  const response = await request("analyze_turn", {
+    message: "次はアカウント削除について教えて",
+    source: "astera-app",
+    context: { user_goal: "クレジット未反映を解決する", active_topic: "credit", turns: [] },
+  });
+  assert.equal(response.ok, true);
+  assert.equal(response.result.active_topic, "account");
+  assert.equal(response.result.new_topic, true);
+});
+
+test("verification rejects missing coverage unknown evidence and generic non-answer", async () => {
+  const response = await request("verify_turn", {
+    answer: "お問い合わせください。",
+    analysis: { follow_up: false, active_topic: "credit" },
+    returned_topic: "credit",
+    question_task_ids: ["q1", "q2"],
+    answered_task_ids: ["q1"],
+    unresolved_task_ids: [],
+    used_evidence_ids: ["kb:unknown"],
+    available_evidence_ids: ["kb:credit"],
+  });
+  assert.equal(response.ok, true);
+  assert.equal(response.result.passed, false);
+  assert.ok(response.result.violations.includes("question_coverage_missing"));
+  assert.ok(response.result.violations.includes("unknown_evidence_reference"));
+  assert.ok(response.result.violations.includes("generic_non_answer"));
+});
+
+test("verification rejects topic drift private paths and unsafe action claims", async () => {
+  const response = await request("verify_turn", {
+    answer: "As an AI, /internal/admin で削除しました",
+    analysis: { follow_up: true, active_topic: "credit" },
+    returned_topic: "account",
+    question_task_ids: ["q1"],
+    answered_task_ids: ["q1"],
+    unresolved_task_ids: [],
+    used_evidence_ids: [],
+    available_evidence_ids: [],
+  });
+  assert.equal(response.ok, true);
+  assert.equal(response.result.passed, false);
+  assert.ok(response.result.violations.includes("conversation_topic_drift"));
+  assert.ok(response.result.violations.includes("internal_implementation"));
+  assert.ok(response.result.violations.includes("unverified_action_claim"));
+});