databricks-tellr-app 0.4.3.dev20__tar.gz → 0.4.3.dev21__tar.gz

{databricks_tellr_app-0.4.3.dev20 → databricks_tellr_app-0.4.3.dev21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databricks-tellr-app
-Version: 0.4.3.dev20
+Version: 0.4.3.dev21
 Summary: Tellr application package for Databricks Apps
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{databricks_tellr_app-0.4.3.dev20 → databricks_tellr_app-0.4.3.dev21}/databricks_tellr_app.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: databricks-tellr-app
-Version: 0.4.3.dev20
+Version: 0.4.3.dev21
 Summary: Tellr application package for Databricks Apps
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown

{databricks_tellr_app-0.4.3.dev20 → databricks_tellr_app-0.4.3.dev21}/databricks_tellr_app.egg-info/SOURCES.txt

@@ -82,6 +82,14 @@ setup.py
 ./src/core/settings_db.py
 ./src/core/strip_retired_prompt_keys.py
 ./src/core/user_context.py
+./src/core/skills/__init__.py
+./src/core/skills/architect.py
+./src/core/skills/build_reviewer.py
+./src/core/skills/builder.py
+./src/core/skills/data_analyst.py
+./src/core/skills/deck_reviewer.py
+./src/core/skills/fix_reviewer.py
+./src/core/skills/fixer.py
 ./src/database/__init__.py
 ./src/database/types.py
 ./src/database/models/__init__.py
@@ -114,6 +122,7 @@ setup.py
 ./src/services/__init__.py
 ./src/services/agent.py
 ./src/services/agent_factory.py
+./src/services/agent_resolution.py
 ./src/services/config_service.py
 ./src/services/config_validator.py
 ./src/services/deck_css_aggregator.py
@@ -122,6 +131,7 @@ setup.py
 ./src/services/design_system_service.py
 ./src/services/design_system_templates.py
 ./src/services/drive_uploader.py
+./src/services/foreman_service.py
 ./src/services/genie_service.py
 ./src/services/google_slides_auth.py
 ./src/services/google_slides_prompts_defaults.py
@@ -135,7 +145,9 @@ setup.py
 ./src/services/pptx_from_records.py
 ./src/services/pptx_prompts_defaults.py
 ./src/services/profile_service.py
+./src/services/spec_sync.py
 ./src/services/streaming_callback.py
+./src/services/template_sections.py
 ./src/services/validator.py
 ./src/services/converter_jail/__init__.py
 ./src/services/converter_jail/ast_guard.py
@@ -146,6 +158,12 @@ setup.py
 ./src/services/converter_jail/protocol.py
 ./src/services/evaluation/__init__.py
 ./src/services/evaluation/llm_judge.py
+./src/services/graph/__init__.py
+./src/services/graph/builder.py
+./src/services/graph/event_emitter.py
+./src/services/graph/nodes.py
+./src/services/graph/routers.py
+./src/services/graph/state.py
 ./src/services/identity_providers/__init__.py
 ./src/services/identity_providers/account_provider.py
 ./src/services/identity_providers/local_provider.py
@@ -161,6 +179,7 @@ setup.py
 ./src/utils/css_utils.py
 ./src/utils/ds_asset_utils.py
 ./src/utils/error_handling.py
+./src/utils/graph_safety.py
 ./src/utils/html_safety.py
 ./src/utils/html_utils.py
 ./src/utils/image_utils.py
@@ -256,6 +275,14 @@ src/core/prompt_modules.py
 src/core/settings_db.py
 src/core/strip_retired_prompt_keys.py
 src/core/user_context.py
+src/core/skills/__init__.py
+src/core/skills/architect.py
+src/core/skills/build_reviewer.py
+src/core/skills/builder.py
+src/core/skills/data_analyst.py
+src/core/skills/deck_reviewer.py
+src/core/skills/fix_reviewer.py
+src/core/skills/fixer.py
 src/database/__init__.py
 src/database/types.py
 src/database/models/__init__.py
@@ -288,6 +315,7 @@ src/domain/slide_deck.py
 src/services/__init__.py
 src/services/agent.py
 src/services/agent_factory.py
+src/services/agent_resolution.py
 src/services/config_service.py
 src/services/config_validator.py
 src/services/deck_css_aggregator.py
@@ -296,6 +324,7 @@ src/services/design_system_compiler.py
 src/services/design_system_service.py
 src/services/design_system_templates.py
 src/services/drive_uploader.py
+src/services/foreman_service.py
 src/services/genie_service.py
 src/services/google_slides_auth.py
 src/services/google_slides_prompts_defaults.py
@@ -309,7 +338,9 @@ src/services/pptx_from_html_huashu.py
 src/services/pptx_from_records.py
 src/services/pptx_prompts_defaults.py
 src/services/profile_service.py
+src/services/spec_sync.py
 src/services/streaming_callback.py
+src/services/template_sections.py
 src/services/validator.py
 src/services/converter_jail/__init__.py
 src/services/converter_jail/ast_guard.py
@@ -320,6 +351,12 @@ src/services/converter_jail/pptx_runner.py
 src/services/converter_jail/protocol.py
 src/services/evaluation/__init__.py
 src/services/evaluation/llm_judge.py
+src/services/graph/__init__.py
+src/services/graph/builder.py
+src/services/graph/event_emitter.py
+src/services/graph/nodes.py
+src/services/graph/routers.py
+src/services/graph/state.py
 src/services/identity_providers/__init__.py
 src/services/identity_providers/account_provider.py
 src/services/identity_providers/local_provider.py
@@ -335,6 +372,7 @@ src/utils/__init__.py
 src/utils/css_utils.py
 src/utils/ds_asset_utils.py
 src/utils/error_handling.py
+src/utils/graph_safety.py
 src/utils/html_safety.py
 src/utils/html_utils.py
 src/utils/image_utils.py

{databricks_tellr_app-0.4.3.dev20 → databricks_tellr_app-0.4.3.dev21}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "databricks-tellr-app"
-version = "0.4.3.dev20"
+version = "0.4.3.dev21"
 description = "Tellr application package for Databricks Apps"
 readme = "README.md"
 requires-python = ">=3.10"

{databricks_tellr_app-0.4.3.dev20 → databricks_tellr_app-0.4.3.dev21}/src/api/fixtures/tour_demo_deck.json

@@ -24,5 +24,56 @@
     }
   ],
   "chat_prompt": "Create 3 slides about the benefits of AI in modern healthcare, with a title slide, key advantages, and future outlook.",
-  "chat_reply": "Here's your deck with 3 slides! I've created:\n\n1. **Title Slide** — introducing AI in healthcare\n2. **Key Advantages** — early detection, personalized treatment, operational efficiency, and drug discovery\n3. **Future Outlook** — predictive monitoring, AI-assisted surgery, and global health equity\n\nFeel free to ask me to refine any slide, add new ones, or change the style."
+  "chat_reply": "Here's your deck with 3 slides! I've created:\n\n1. **Title Slide** — introducing AI in healthcare\n2. **Key Advantages** — early detection, personalized treatment, operational efficiency, and drug discovery\n3. **Future Outlook** — predictive monitoring, AI-assisted surgery, and global health equity\n\nFeel free to ask me to refine any slide, add new ones, or change the style.",
+  "deck_spec": {
+    "title": "Example Deck — AI in Healthcare",
+    "audience": "A first-time Tellr user taking the product tour: a general business audience, with no clinical or machine-learning background assumed.",
+    "purpose": "Show a new user what a finished Tellr deck looks like, on a subject that needs no domain briefing, so they can see structure and styling before they write their own prompt.",
+    "argument": "AI already delivers concrete benefits across diagnosis, treatment and research, and its near-term trajectory points at prevention and wider access, so it is worth engaging with now rather than watching.",
+    "call_to_action": "Ask the assistant to refine a slide, add a new one, or change the style: the next step of the tour.",
+    "narrative_arc": [
+      "Frame the subject: AI is already changing patient care, diagnostics and medical research, a transformation under way rather than a forecast.",
+      "Ground that claim in four advantages visible today: earlier disease detection, personalized treatment, operational efficiency, and faster drug discovery.",
+      "Extend today's gains into the near future and land on access: predictive monitoring, AI-assisted surgery, and specialist-level care reaching underserved communities."
+    ],
+    "design_contract": {
+      "design_system_id": null,
+      "template_id": null,
+      "slide_style_id": null
+    },
+    "resolved_data": {
+      "synthesis": "No live data was resolved for this deck. The tour ships fixed illustrative bytes so every user sees the same three slides; the claims are widely reported general benefits of AI in healthcare, not figures drawn from a source system.",
+      "figures": [],
+      "gaps": [
+        "No quantitative source: the deck cites no measured figure, so no claim in it is traceable to a dataset.",
+        "No organisation context: the tour deck is deliberately generic and names no customer, hospital or vendor."
+      ]
+    },
+    "slides": [
+      {
+        "position": 0,
+        "purpose": "Open the deck: name the subject and frame AI in healthcare as a transformation already under way.",
+        "content_brief": "Title slide. Badge reading 'AI & Healthcare', headline 'The Benefits of AI in Modern Healthcare', and a one-line standfirst naming the three areas the deck covers: patient care, diagnostics, and medical research.",
+        "assumes": "Nothing. This is the deck's first slide.",
+        "hands_off": "The reader knows the subject and expects concrete advantages next.",
+        "data_references": []
+      },
+      {
+        "position": 1,
+        "purpose": "Make the case with four concrete present-day advantages, so the benefit claim is specific rather than atmospheric.",
+        "content_brief": "Four bolded items, one explanatory clause each: early disease detection (imaging patterns a human reader can miss), personalized treatment plans (genetics, lifestyle, history), operational efficiency (scheduling, documentation, triage), and drug discovery acceleration (molecular simulation at scale).",
+        "assumes": "The reader has accepted the framing from the title slide.",
+        "hands_off": "The present-tense case is made; the reader is ready to look forward.",
+        "data_references": []
+      },
+      {
+        "position": 2,
+        "purpose": "Extend the argument from today's gains to the near future and close on access, so the deck ends on consequence rather than a list.",
+        "content_brief": "Three bolded forward-looking items: predictive health monitoring (wearables shifting medicine from reactive to proactive), AI-assisted surgery (robotics guided by real-time analysis), and global health equity (mobile diagnostics for underserved communities). Close on the italic line about healthcare becoming intelligent, personalized and accessible to all.",
+        "assumes": "The reader accepts the four present-day advantages from the previous slide.",
+        "hands_off": "The deck ends; the reader leaves with the equity claim as the takeaway.",
+        "data_references": []
+      }
+    ]
+  }
 }

{databricks_tellr_app-0.4.3.dev20 → databricks_tellr_app-0.4.3.dev21}/src/api/main.py

@@ -51,13 +51,14 @@ _worker_task = None
 _export_worker_task = None
 _cleanup_task = None
 _timeout_task = None
+_spec_sweeper_task = None
 _frontend_assets_stack: ExitStack | None = None
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
     """Lifespan context manager for startup/shutdown events."""
-    global _worker_task, _export_worker_task, _cleanup_task, _timeout_task, _frontend_assets_stack
+    global _worker_task, _export_worker_task, _cleanup_task, _timeout_task, _spec_sweeper_task, _frontend_assets_stack
 
     # Startup
     logger.info(f"Starting AI Slide Generator API (environment: {ENVIRONMENT})")
@@ -134,6 +135,16 @@ async def lifespan(app: FastAPI):
         _cleanup_task = asyncio.create_task(request_log_cleanup_loop())
         logger.info("Request log cleanup task started")
 
+        # Start the spec-dirty arc-review sweeper. A PERIODIC LOOP, so it belongs
+        # here beside the two above and NOT in run.py::init_database: the
+        # pre-fork rule there is for migrations and backfills, which must run
+        # exactly once, and a loop started in that step would die with it. It
+        # runs in every uvicorn worker (UVICORN_WORKERS defaults to 4), which is
+        # why claim_due_marker takes an atomic lease rather than trusting a read.
+        from src.services.spec_sync import spec_review_sweeper_loop
+        _spec_sweeper_task = asyncio.create_task(spec_review_sweeper_loop())
+        logger.info("Spec-review arc sweeper started")
+
         # Recover any stuck requests from previous crashes
         try:
             recovered = await recover_stuck_requests()
@@ -185,6 +196,14 @@ async def lifespan(app: FastAPI):
             pass
         logger.info("MCP job timeout sweeper stopped")
 
+    if _spec_sweeper_task:
+        _spec_sweeper_task.cancel()
+        try:
+            await _spec_sweeper_task
+        except asyncio.CancelledError:
+            pass
+        logger.info("Spec-review arc sweeper stopped")
+
     # Tear down the FastMCP session manager's task group. Safe to call
     # unconditionally — the stack was entered unconditionally at startup.
     await mcp_lifespan_stack.aclose()

{databricks_tellr_app-0.4.3.dev20 → databricks_tellr_app-0.4.3.dev21}/src/api/routes/chat.py

@@ -26,7 +26,7 @@ from src.api.schemas.requests import ChatRequest
 from src.api.schemas.responses import ChatResponse
 from src.api.schemas.streaming import StreamEvent, StreamEventType
 from src.api.routes._authz import _check_deck_permission_for_session
-from src.api.services.chat_service import get_chat_service
+from src.api.services.chat_service import get_chat_service, resolve_engine_mode_or
 from src.api.services.job_queue import enqueue_job
 from src.api.services.session_manager import SessionNotFoundError, get_session_manager
 from src.core.context_utils import run_in_thread_with_context
@@ -454,6 +454,15 @@ async def send_message_streaming(
             detail="Session is currently processing another request. Please wait.",
         )
 
+    # ws4d D2 — the engine for this turn is resolved HERE, in the chat route,
+    # and passed down.  Not in send_message_streaming and not in the job queue:
+    # MCP's enqueue_create_job drains through the same worker as POST
+    # /chat/async, so a resolution downstream of enqueue_job would put MCP on
+    # the graph.  Resolution reads the database, so it runs off the event loop.
+    engine_mode = await asyncio.to_thread(
+        resolve_engine_mode_or, request.session_id
+    )
+
     async def generate_events() -> AsyncGenerator[str, None]:
         """Generate SSE events from the chat service."""
         import queue
@@ -484,6 +493,7 @@ async def send_message_streaming(
                     if request.slide_context
                     else None,
                     image_ids=request.image_ids,
+                    engine_mode=engine_mode,
                 ):
                     event_queue.put(event)
             except Exception as e:
@@ -637,6 +647,14 @@ async def submit_chat_async(
             request_id=request_id,
         )
 
+        # ws4d D2 — resolved AFTER the user message is persisted just above,
+        # because resolve_engine_mode reads the deck's EARLIEST role='user'
+        # message: on turn 1 that row has to exist already or the phrase in the
+        # very first message would resolve to monolith.
+        engine_mode = await asyncio.to_thread(
+            resolve_engine_mode_or, request.session_id
+        )
+
         # Queue for processing
         await enqueue_job(
             request_id,
@@ -648,6 +666,10 @@ async def submit_chat_async(
                 ),
                 "is_first_message": is_first_message,
                 "image_ids": request.image_ids,
+                # `engine_mode`, NEVER `mode`: `mode` is already MCP's
+                # generate/edit flag in this same payload (mcp_server.py), whose
+                # values are neither "graph" nor "monolith".
+                "engine_mode": engine_mode,
             },
         )
 
@@ -669,18 +691,36 @@ async def submit_chat_async(
 async def poll_chat(
     request_id: str,
     after_message_id: int = Query(default=0, description="Return messages after this ID"),
+    slide_cursor: int = Query(
+        default=0, description="Lowest slide position not yet delivered"
+    ),
 ):
-    """Poll for chat request status and new messages.
+    """Poll for chat request status, new messages, and newly released slides.
 
-    Returns the current request status and any new messages since
-    the last poll (based on after_message_id).
+    Returns the current request status, any new messages since the last poll
+    (based on after_message_id), and any slides the reorder buffer has released
+    since ``slide_cursor``.
+
+    **The slides do NOT come through ``msg_to_stream_event``.**  ws4d D3 does not
+    persist slide-ready as a ``SessionMessage``: that converter returns a fixed
+    six-key dict with nowhere to put ``position``/``html``/``scripts``, so a
+    converter that learned the type still could not carry the data — and build
+    mechanics in the transcript pollute a view that is now user-visible and
+    clearable.  This reads **committed rows** instead, via
+    ``SessionManager.slides_since_cursor``, which is the same reorder-buffer prefix
+    rule the graph applies to state on the SSE transport.
 
     Args:
         request_id: Request ID from submit_chat_async
         after_message_id: Return messages with ID greater than this
+        slide_cursor: Lowest slide position the caller has NOT been sent.  ``0``
+            (the default) asks for every released slide.  Positions are 0-based,
+            so this is inclusive — unlike ``after_message_id``, whose ids start
+            at 1.  Hand back the ``slide_cursor`` from the previous response.
 
     Returns:
-        Dictionary with status, events, last_message_id, and result
+        Dictionary with status, events, last_message_id, result, error, slides
+        and slide_cursor
 
     Raises:
         HTTPException: 404 if request not found
@@ -721,10 +761,33 @@ async def poll_chat(
         if m["role"] != "user"
     ]
 
+    # ws4d D3 — incremental slides on the polling transport.  Projected into an
+    # explicit response shape rather than returned as-is: the row query knows
+    # about columns this endpoint has no business shipping, and the four keys
+    # below are the contract ws4e consumes.
+    released_slides = [
+        {
+            "position": row["position"],
+            "html": row["html"],
+            "scripts": row["scripts"],
+            "agent": row["agent"],
+        }
+        for row in await asyncio.to_thread(
+            session_manager.slides_since_cursor, session_id, slide_cursor
+        )
+    ]
+
     return {
         "status": chat_request["status"],
         "events": events,
         "last_message_id": messages[-1]["id"] if messages else after_message_id,
         "result": chat_request.get("result") if chat_request["status"] == "completed" else None,
         "error": chat_request.get("error_message") if chat_request["status"] == "error" else None,
+        "slides": released_slides,
+        # The next position NOT yet delivered.  Unchanged when nothing was
+        # released, so a client that keeps handing this back never re-receives a
+        # slide it already has.
+        "slide_cursor": (
+            released_slides[-1]["position"] + 1 if released_slides else slide_cursor
+        ),
     }

{databricks_tellr_app-0.4.3.dev20 → databricks_tellr_app-0.4.3.dev21}/src/api/routes/sessions.py

@@ -22,6 +22,7 @@ from src.api.routes._authz import (
     _require_session_access,
 )
 from src.api.schemas.requests import CreateSessionRequest, DuplicateSessionRequest
+from src.api.services.chat_service import get_chat_service
 from src.api.services.session_manager import (
     SessionAccessDeniedError,
     SessionNotFoundError,
@@ -704,6 +705,57 @@ async def add_message(session_id: str, request: AddMessageRequest):
         ) from e
 
 
+@router.delete("/{session_id}/context")
+async def clear_session_context(session_id: str):
+    """Clear the conversation context for a session, keeping the deck and its spec.
+
+    Drops the transcript and the graph checkpoint thread; keeps the slide deck,
+    ``deck_spec_json`` (the structured compaction of what was decided) and the
+    earliest user message, which is what engine-mode resolution reads.
+
+    Requires CAN_EDIT: the helper's default is CAN_VIEW, and taking the default
+    would let a **viewer** wipe another user's transcript and graph thread.
+
+    Args:
+        session_id: Session whose context to clear
+
+    Returns:
+        Clear confirmation with the number of messages deleted
+    """
+    # Permission check: require CAN_EDIT on the deck — NOT the helper's default.
+    await asyncio.to_thread(
+        _check_deck_permission_for_session, session_id, PermissionLevel.CAN_EDIT
+    )
+
+    try:
+        chat_service = get_chat_service()
+        result = await asyncio.to_thread(chat_service.clear_context, session_id)
+
+        logger.info(
+            "Session context cleared via API",
+            extra={
+                "session_id": session_id,
+                "deleted_messages": result.get("deleted_messages"),
+            },
+        )
+
+        return result
+
+    except SessionNotFoundError:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Session not found: {session_id}",
+        )
+    except HTTPException:
+        raise
+    except Exception as e:
+        logger.error(f"Failed to clear session context: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail="Failed to clear session context",
+        ) from e
+
+
 @router.get("/{session_id}/slides")
 async def get_session_slides(session_id: str):
     """Get slide deck for a session.

{databricks_tellr_app-0.4.3.dev20 → databricks_tellr_app-0.4.3.dev21}/src/api/routes/slides.py

@@ -7,6 +7,26 @@ Slide access is controlled by session permissions:
 - CAN_VIEW: Can view slides (via get_slides)
 - CAN_EDIT: Can modify slides (reorder, update, duplicate, delete)
 - CAN_MANAGE: Full control (same as owner)
+
+The spec-dirty trigger lives in THIS module and nowhere else
+------------------------------------------------------------
+Five handlers below call ``spec_sync.mark_dirty`` after their mutation commits:
+insert, reorder, update, duplicate and delete.  That is the whole of the trigger surface —
+the LangGraph deck build calls the ``chat_service`` / ``slide_repository`` /
+``deck_level_writer`` methods these handlers wrap, and never issues an HTTP
+request, so "arrived via a route" *means* "a human did this" by construction.  No
+``origin=`` parameter to forget, no ContextVar to leak.
+``tests/unit/test_spec_sync_placement.py`` fails if any other module under ``src/``
+references the name, and pins which routes do and do not trigger.  Read
+``src/services/spec_sync.py``'s module docstring before adding or moving a call.
+
+``get_current_user()`` is read in the handler's own request context and the author
+passed explicitly into the worker thread — never re-read inside the thread.
+
+Deliberately NOT triggers: the two verification routes and the three version
+routes (a version save does not change the live deck; a restore cancels the
+pending review instead), and session-duplicate in ``sessions.py`` (a copied spec
+is already correct for the HTML it carries).
 """
 
 import asyncio
@@ -28,6 +48,7 @@ from src.core.database import get_db
 from src.core.permission_context import get_permission_context  # noqa: F401 — patched by integration-test fixtures
 from src.core.user_context import get_current_user  # noqa: F401 — patched by integration-test fixtures
 from src.database.models.profile_contributor import PermissionLevel
+from src.services.spec_sync import mark_dirty
 
 logger = logging.getLogger(__name__)
 
@@ -57,6 +78,27 @@ class SlideActionRequest(BaseModel):
     expected_version: Optional[int] = None
 
 
+class InsertSlideRequest(BaseModel):
+    """Request to insert a new slide at a position.
+
+    ``position`` is 0-based and NOT bounded above: a position past the end appends,
+    which is `SlideDeck.insert_slide`'s own behaviour and is deliberately not
+    re-implemented here. The lower bound IS enforced — not by a pydantic
+    constraint, but by `chat_service.insert_slide` raising ValueError, which this
+    handler turns into a 400 — because `list.insert` would read a negative position
+    as counting backwards from the end and land the slide somewhere the caller did
+    not ask for.
+
+    ``html`` is optional: omitted, an empty slide is inserted for a human or the
+    architect to fill.
+    """
+
+    session_id: str
+    position: int
+    html: Optional[str] = None
+    expected_version: Optional[int] = None
+
+
 class UpdateVerificationRequest(BaseModel):
     """Request to update a slide's verification result."""
 
@@ -108,6 +150,83 @@ async def get_slides(
         raise HTTPException(status_code=500, detail="Internal server error")
 
 
+@router.post("")
+async def insert_slide(request: InsertSlideRequest, db: Session = Depends(get_db)):
+    """Insert a new slide, shifting every slide above the insertion point up.
+
+    Requires CAN_EDIT permission — the level is pinned by
+    ``tests/unit/test_authz_slides_insert.py``, not by
+    ``test_route_authz_coverage.py``, which checks that a route has *a* check and
+    cannot detect a wrong LEVEL.
+    Uses session locking to prevent concurrent modifications.
+
+    Args:
+        request: InsertSlideRequest with session_id, position and optional html
+
+    Returns:
+        Updated slide deck
+
+    Raises:
+        HTTPException: 403 if no permission, 400 for validation errors, 409 if
+            session busy or version conflict, 423 if another user holds the
+            editing lock, 500 on error
+    """
+    _require_slide_permission(request.session_id, db, PermissionLevel.CAN_EDIT)
+
+    session_manager = get_session_manager()
+
+    try:
+        await run_in_thread_with_context(session_manager.require_editing_lock, request.session_id)
+    except PermissionError as e:
+        raise HTTPException(status_code=423, detail=str(e))
+
+    locked = await asyncio.to_thread(
+        session_manager.acquire_session_lock,
+        request.session_id,
+    )
+    if not locked:
+        raise HTTPException(
+            status_code=409,
+            detail="Session is currently processing another request. Please wait.",
+        )
+
+    try:
+        chat_service = get_chat_service()
+        result = await asyncio.to_thread(
+            chat_service.insert_slide,
+            request.session_id,
+            request.position,
+            html=request.html,
+            expected_version=request.expected_version,
+        )
+
+        logger.info(
+            "Inserted slide",
+            extra={"position": request.position, "session_id": request.session_id},
+        )
+        # A slide was added: the deck's slide list no longer matches the spec's.
+        # The service gave the new position a PLACEHOLDER spec entry with no
+        # purpose, so this is also what schedules the description of it.
+        await asyncio.to_thread(mark_dirty, request.session_id, get_current_user())
+        return result
+
+    except VersionConflictError as e:
+        raise HTTPException(status_code=409, detail=str(e))
+    except PermissionError as e:
+        raise HTTPException(status_code=423, detail=str(e))
+    except ValueError as e:
+        logger.warning(f"Validation error in insert_slide: {e}")
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        logger.error(f"Failed to insert slide: {e}", exc_info=True)
+        raise HTTPException(status_code=500, detail="Internal server error")
+    finally:
+        await asyncio.to_thread(
+            session_manager.release_session_lock,
+            request.session_id,
+        )
+
+
 @router.put("/reorder")
 async def reorder_slides(request: ReorderRequest, db: Session = Depends(get_db)):
     """Reorder slides.
@@ -156,6 +275,9 @@ async def reorder_slides(request: ReorderRequest, db: Session = Depends(get_db))
             "Reordered slides",
             extra={"new_order": request.new_order, "session_id": request.session_id},
         )
+        # A reorder mutates the narrative arc with NO HTML change, so a
+        # content-hash trigger would miss it entirely.
+        await asyncio.to_thread(mark_dirty, request.session_id, get_current_user())
         return result
 
     except VersionConflictError as e:
@@ -224,6 +346,8 @@ async def update_slide(index: int, request: UpdateSlideRequest, db: Session = De
             "Updated slide",
             extra={"index": index, "session_id": request.session_id},
         )
+        # The human HTML edit — the reason the marker exists.
+        await asyncio.to_thread(mark_dirty, request.session_id, get_current_user())
         return result
 
     except VersionConflictError as e:
@@ -292,6 +416,8 @@ async def duplicate_slide(index: int, request: SlideActionRequest, db: Session =
             "Duplicated slide",
             extra={"index": index, "session_id": request.session_id},
         )
+        # A slide was added: the deck's slide list no longer matches the spec's.
+        await asyncio.to_thread(mark_dirty, request.session_id, get_current_user())
         return result
 
     except VersionConflictError as e:
@@ -366,6 +492,9 @@ async def delete_slide(
             "Deleted slide",
             extra={"index": index, "session_id": session_id},
         )
+        # A slide was removed.  Note this handler takes session_id from the query
+        # string, not a request body.
+        await asyncio.to_thread(mark_dirty, session_id, get_current_user())
         return result
 
     except VersionConflictError as e: