databricks-tellr-app 0.5.1.dev1__tar.gz → 0.5.1.dev3__tar.gz

{databricks_tellr_app-0.5.1.dev1 → databricks_tellr_app-0.5.1.dev3}/PKG-INFO

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

{databricks_tellr_app-0.5.1.dev1 → databricks_tellr_app-0.5.1.dev3}/databricks_tellr_app.egg-info/PKG-INFO

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

{databricks_tellr_app-0.5.1.dev1 → databricks_tellr_app-0.5.1.dev3}/databricks_tellr_app.egg-info/SOURCES.txt

@@ -133,6 +133,7 @@ setup.py
 ./src/domain/slide_alignment.py
 ./src/domain/slide_deck.py
 ./src/domain/slide_numbering.py
+./src/domain/slide_operations.py
 ./src/services/__init__.py
 ./src/services/agent.py
 ./src/services/agent_definition_manifest_v1.py
@@ -372,6 +373,7 @@ src/domain/slide.py
 src/domain/slide_alignment.py
 src/domain/slide_deck.py
 src/domain/slide_numbering.py
+src/domain/slide_operations.py
 src/services/__init__.py
 src/services/agent.py
 src/services/agent_definition_manifest_v1.py

{databricks_tellr_app-0.5.1.dev1 → databricks_tellr_app-0.5.1.dev3}/pyproject.toml

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

{databricks_tellr_app-0.5.1.dev1 → databricks_tellr_app-0.5.1.dev3}/src/api/services/session_manager.py

@@ -712,8 +712,11 @@ def _rewrite_slide_rows(
 ) -> None:
     """THE per-slide rewrite of a whole deck: one copy, so its callers cannot diverge.
 
-    ``save_slide_deck``, ``restore_version`` and ``SlideWriter.insert_pending_slides``
-    all rewrite every row of a deck through here.  Hand-copied versions of this
+    ``save_slide_deck``, ``restore_version`` and :func:`_lay_out_slide_rows` all
+    rewrite every row of a deck through here.  ``_lay_out_slide_rows`` is the
+    exact-map shift behind ``SlideWriter.apply_slide_layout`` (and so its
+    ``insert_pending_slides`` special case) and, through :func:`_splice_slide_rows`,
+    the manual ``SessionManager.insert_slide``.  Hand-copied versions of this
     block once drifted apart, and a reorder then attached slide identity and
     verdicts to the wrong slide.
 
@@ -817,22 +820,22 @@ def _splice_slide_rows(
     old_rows: List[SessionSlide],
     new_slides: Mapping[int, Tuple[Dict[str, Any], Dict[str, Any]]],
 ) -> None:
-    """THE shift: splice new slides in among a deck's rows with the EXACT old-row map.
+    """Splice new slides in among a deck's rows, in order: the in-order wrapper.
 
-    Shared by the graph's ``SlideWriter.insert_pending_slides`` and the manual
-    ``SessionManager.insert_slide``, so there is one shift primitive and one row
-    writer.
+    The manual ``SessionManager.insert_slide``'s shift.  It only builds the
+    in-order layout and hands it to :func:`_lay_out_slide_rows`, THE shift
+    primitive, which the graph's ``SlideWriter.apply_slide_layout`` (and so its
+    ``insert_pending_slides`` special case) calls directly — so there is one
+    shift primitive and one row writer.
 
-    1. Every old row is snapshotted (:func:`_snapshot_row`) and attributed
-       (:func:`_attribution_from`) BEFORE any write: ``_upsert_slide_row``
-       rewrites those ORM rows in place.
-    2. ``len(old_rows) + len(new_slides)`` positions are laid out: position ``i``
+    1. ``len(old_rows) + len(new_slides)`` positions are laid out: position ``i``
        holds ``new_slides[i]``'s slide when ``i`` is a key, otherwise the next old
        row in order.
-    3. Every position is rewritten through ``_rewrite_slide_rows`` with that map,
-       never the attribution heuristic, and with ``now_dt=None`` /
-       ``author_fallback=None``, so a moved row with a NULL author or timestamp
-       stays NULL and no moved row gets a fresh ``modified_at``.
+    2. :func:`_lay_out_slide_rows` snapshots and attributes every old row BEFORE
+       any write and rewrites every position with that exact map, never the
+       attribution heuristic, and with ``now_dt=None`` / ``author_fallback=None``,
+       so a moved row with a NULL author or timestamp stays NULL and no moved row
+       gets a fresh ``modified_at``.
 
     Args:
         db: live SQLAlchemy session; the caller owns the transaction.
@@ -854,26 +857,82 @@ def _splice_slide_rows(
             f"{new_count} positions"
         )
 
+    layout = []
+    old_index = 0
+    for new_index in range(new_count):
+        if new_index in new_slides:
+            layout.append(None)
+        else:
+            layout.append(old_index)
+            old_index += 1
+    _lay_out_slide_rows(db, owner_id, old_rows, layout, new_slides)
+
+
+def _lay_out_slide_rows(
+    db: Session,
+    owner_id: int,
+    old_rows: List[SessionSlide],
+    layout: Sequence[Optional[int]],
+    new_slides: Mapping[int, Tuple[Dict[str, Any], Dict[str, Any]]],
+) -> None:
+    """THE shift primitive: lay a deck's rows out in any order, with the EXACT map.
+
+    ``layout[i]`` is the INDEX into ``old_rows`` (position order) whose row lands
+    at new index ``i``, or ``None`` for a new slide, whose
+    ``(slide_dict, incoming_record)`` is ``new_slides[i]``.  An old index may
+    appear at most once; one that is absent is deleted (pruned, with its record
+    and spec fragment).  Every exact-map writer goes through here:
+    ``SlideWriter.apply_slide_layout`` (the graph's operations layout, and its
+    ``insert_pending_slides`` special case) directly, and the manual
+    ``SessionManager.insert_slide`` through :func:`_splice_slide_rows`, the
+    in-order wrapper.
+
+    1. Every old row is snapshotted (:func:`_snapshot_row`) and attributed
+       (:func:`_attribution_from`) BEFORE any write: ``_upsert_slide_row``
+       rewrites those ORM rows in place.
+    2. Every position is rewritten through ``_rewrite_slide_rows`` with that exact
+       map, never the attribution heuristic, and with ``now_dt=None`` /
+       ``author_fallback=None``, so a moved row with a NULL author or timestamp
+       stays NULL and no moved row gets a fresh ``modified_at``.
+    3. Rows beyond ``len(layout)`` are pruned (inside ``_rewrite_slide_rows``).
+
+    Raises:
+        ValueError: the layout is malformed (an old index repeated or outside
+            ``range(len(old_rows))``, or ``new_slides`` keys that are not exactly
+            the ``None`` indices).  Raised before anything is written.
+    """
+    layout = list(layout)
+    old_count = len(old_rows)
+    kept = [index for index in layout if index is not None]
+    bad = sorted({index for index in kept if not 0 <= index < old_count})
+    if bad:
+        raise ValueError(f"layout names old rows {bad} outside range({old_count})")
+    if len(set(kept)) != len(kept):
+        raise ValueError(f"layout names an old row more than once: {layout}")
+    new_positions = {i for i, index in enumerate(layout) if index is None}
+    if set(new_slides) != new_positions:
+        raise ValueError(
+            f"new_slides keys {sorted(new_slides)} are not the layout's new "
+            f"positions {sorted(new_positions)}"
+        )
+
     # 1. Snapshots and attributions from the ORM rows BEFORE any write.
     snapshots = [_snapshot_row(row) for row in old_rows]
     attributions = [_attribution_from(row) for row in old_rows]
 
-    # 2. The layout: each new slide at its index, the old rows in order around them.
     slides: List[Dict[str, Any]] = []
     attribution: Dict[int, SlideAttribution] = {}
     incoming: Dict[int, Dict[str, Any]] = {}
-    old_index = 0
-    for new_index in range(new_count):
-        if new_index in new_slides:
+    for new_index, old_index in enumerate(layout):
+        if old_index is None:
             slide_dict, record = new_slides[new_index]
             slides.append(slide_dict)
             incoming[new_index] = record
         else:
             slides.append(snapshots[old_index])
             attribution[new_index] = attributions[old_index]
-            old_index += 1
 
-    # 3. THE whole-deck rewrite, with the exact map.
+    # 2-3. THE whole-deck rewrite, with the exact map, then the prune.
     _rewrite_slide_rows(
         db,
         owner_id,
@@ -2168,8 +2227,9 @@ class SessionManager:
         """Insert one slide (the viewer's manual insert) in ONE transaction.
 
         The manual insert shifts every later slide by one, so it moves rows with
-        the EXACT old-row map (:func:`_splice_slide_rows`, shared with the graph's
-        ``SlideWriter.insert_pending_slides``), never ``save_slide_deck``'s
+        the EXACT old-row map (:func:`_splice_slide_rows`, the in-order wrapper of
+        :func:`_lay_out_slide_rows`, the shift primitive the graph's
+        ``SlideWriter.apply_slide_layout`` also uses), never ``save_slide_deck``'s
         attribution heuristic.  Rows, spec, deck columns and evidence are written
         in one ``get_db_session()``, in this order:
 

{databricks_tellr_app-0.5.1.dev1 → databricks_tellr_app-0.5.1.dev3}/src/api/services/slide_repository.py

@@ -25,8 +25,8 @@ from sqlalchemy import and_
 from src.api.services.session_manager import (
     SessionManager,
     SlideRowsChangedError,
+    _lay_out_slide_rows,
     _snapshot_row,  # noqa: F401 — re-exported; it moved to session_manager
-    _splice_slide_rows,
     get_session_manager,
 )
 from src.core.database import get_db_session
@@ -465,8 +465,9 @@ class SlideWriter:
            EXACT old-row map, never the attribution heuristic, and with
            ``now_dt=None``/``author_fallback=None``, so a moved row with a NULL
            author or timestamp stays NULL and no moved row gets a fresh
-           ``modified_at``.  Steps 2-4 are ``session_manager._splice_slide_rows``,
-           the one shift primitive, shared with ``SessionManager.insert_slide``.
+           ``modified_at``.  Steps 2-4 are ``session_manager._lay_out_slide_rows``
+           (via :meth:`apply_slide_layout`), the one shift primitive, shared with
+           ``SessionManager.insert_slide``.
         5. ``deck_spec_json`` is set to *deck_spec*, ``version`` is bumped (which
            invalidates every worker's deck cache) and ``last_activity`` touched.
            ``slide_count`` is NOT written: its single writer is the post-commit
@@ -516,8 +517,103 @@ class SlideWriter:
                 "insert_pending_slides records an insert_slide/deck mutation, not "
                 f"{mutation.operation}/{mutation.object_type}"
             )
-        expected = [(slide_id, content_hash) for slide_id, content_hash in expected_rows]
         spec_count = len(spec.slides)
+        if insert_at[-1] >= spec_count:
+            raise ValueError(
+                f"insert_at {insert_at} is beyond the spec's {spec_count} slides"
+            )
+        layout: List[Optional[int]]
+        if not expected_rows:
+            # Row-less (spec-only) deck: no rows to lay out, only None slots.
+            layout = [None] * len(insert_at)
+        else:
+            new_count = len(expected_rows) + len(insert_at)
+            if insert_at[-1] >= new_count:
+                raise ValueError(
+                    f"insert_at {insert_at} is beyond the shifted deck's "
+                    f"{new_count} slides"
+                )
+            # The in-order layout: the old rows in order around each inserted index.
+            layout = []
+            old_index = 0
+            for new_index in range(new_count):
+                if new_index in insert_at:
+                    layout.append(None)
+                else:
+                    layout.append(old_index)
+                    old_index += 1
+        return self.apply_slide_layout(
+            session_id,
+            layout,
+            deck_spec=deck_spec,
+            expected_rows=expected_rows,
+            created_by=created_by,
+            mutation=mutation,
+        )
+
+    def apply_slide_layout(
+        self,
+        session_id: str,
+        layout: Sequence[Optional[int]],
+        *,
+        deck_spec: str,
+        expected_rows: Sequence[Tuple[Optional[str], str]],
+        created_by: Optional[str],
+        mutation: DeckMutationContext,
+    ) -> List[str]:
+        """Lay the deck's rows out as *layout*: move, delete and insert in one transaction.
+
+        The general form of :meth:`insert_pending_slides`.  ``layout[i]`` is the
+        INDEX into the current rows (position order) that lands at new index
+        ``i``, or ``None`` for a pending placeholder (``PENDING_SLIDE_TEXT``,
+        fresh ``slide_id``, authored by *created_by*).  A current row whose index
+        is absent is deleted.  Every kept row keeps its whole identity
+        (``slide_id``, authorship, timestamps, verification record, spec
+        fragment), through ``session_manager._lay_out_slide_rows``.
+
+        One ``get_db_session()`` transaction: the rows are re-read and
+        ``[(slide_id, content_hash)]`` must equal *expected_rows*
+        (:class:`SlideRowsChangedError` otherwise, also for a session with no deck
+        row); the layout is validated against the committed rows; the rows are
+        laid out; ``deck_spec_json`` is set to *deck_spec*, ``version`` bumped,
+        ``last_activity`` touched (``slide_count`` is NOT written); and ONE
+        mutation event is recorded.  A row-less (spec-only) deck takes the last
+        two steps only, and its layout must be all ``None``.
+
+        Args:
+            session_id: the requesting session (a contributor writes the owner's deck).
+            layout: see above.
+            deck_spec: the canonical spec JSON of the deck after the edit; with
+                rows, its slide count must equal ``len(layout)``.
+            expected_rows: ``[(slide_id, content_hash)]`` the caller planned against.
+            created_by: the author of the turn that opens the pending rows.
+            mutation: provenance; its actor must be the requesting session, its
+                object type ``deck`` and its operation
+                ``layout_mutation_operation(layout, len(rows))``.
+
+        Returns:
+            The new slides' ``slide_id`` values in ascending new-index order
+            (``[]`` for a row-less deck).
+
+        Raises:
+            ValueError: the layout is malformed or the identity; *deck_spec* is
+                not a valid DeckSpec or its count differs from the layout's;
+                *mutation* does not match the layout; or the evidence write
+                refuses the actor.
+            SlideRowsChangedError: the committed rows are not *expected_rows*, or
+                the session has no deck row.
+            SessionNotFoundError: *session_id* does not match any session.
+
+        Nothing is written on any raise.
+        """
+        layout = list(layout)
+        kept = [index for index in layout if index is not None]
+        if any(index < 0 for index in kept) or len(set(kept)) != len(kept):
+            raise ValueError(f"malformed layout: {layout}")
+        spec = DeckSpec.from_json(deck_spec)
+        if spec is None:
+            raise ValueError("deck_spec is not a valid DeckSpec")
+        expected = [(slide_id, content_hash) for slide_id, content_hash in expected_rows]
 
         with get_db_session() as db:
             session = self.session_manager._get_session_or_raise(db, session_id)
@@ -527,7 +623,7 @@ class SlideWriter:
                 # The caller's prior spec came from this row; its absence means
                 # the deck changed under the planner.
                 raise SlideRowsChangedError(
-                    f"session {session_id} has no deck row to insert into"
+                    f"session {session_id} has no deck row to lay out"
                 )
 
             # 1. The rows the caller planned against, or nothing is written.
@@ -546,29 +642,37 @@ class SlideWriter:
                     f"planned against ({len(committed)} committed, {len(expected)} "
                     "expected)"
                 )
-            if insert_at[-1] >= spec_count:
+
+            # 2. The layout against the committed rows, before any write.
+            if any(index >= len(old_rows) for index in kept):
+                raise ValueError(
+                    f"layout {layout} names a row beyond the deck's {len(old_rows)}"
+                )
+            operation = layout_mutation_operation(layout, len(old_rows))
+            if mutation.operation != operation or mutation.object_type != "deck":
                 raise ValueError(
-                    f"insert_at {insert_at} is beyond the spec's {spec_count} slides"
+                    f"this layout records a {operation}/deck mutation, not "
+                    f"{mutation.operation}/{mutation.object_type}"
                 )
-            new_count = len(old_rows) + len(insert_at)
-            if old_rows and spec_count != new_count:
+            if old_rows and len(spec.slides) != len(layout):
                 raise ValueError(
-                    f"deck_spec has {spec_count} slides, but {len(old_rows)} rows plus "
-                    f"{len(insert_at)} inserted make {new_count}"
+                    f"deck_spec has {len(spec.slides)} slides, but the layout "
+                    f"makes {len(layout)}"
                 )
 
             new_ids: List[str] = []
             now = datetime.utcnow()
             if old_rows:
-                # 2-4. A pending placeholder at each inserted index, spliced in
-                #      through THE shift (session_manager._splice_slide_rows):
-                #      snapshots and attributions before any write, then the
-                #      whole-deck rewrite with the exact old-row map.
+                # 3. A pending placeholder at each None, then THE shift
+                #    (session_manager._lay_out_slide_rows): snapshots and
+                #    attributions before any write, the exact-map rewrite, the prune.
                 pending_html, pending_record = placeholder_slide(
                     PENDING_SLIDE_MESSAGE, text=PENDING_SLIDE_TEXT
                 )
                 new_slides: Dict[int, Tuple[Dict[str, Any], Dict[str, Any]]] = {}
-                for new_index in insert_at:
+                for new_index, old_index in enumerate(layout):
+                    if old_index is not None:
+                        continue
                     slide_id = str(uuid.uuid4())
                     new_ids.append(slide_id)
                     new_slides[new_index] = (
@@ -586,16 +690,16 @@ class SlideWriter:
                             for content_hash, verdict in pending_record.items()
                         },
                     )
-                _splice_slide_rows(db, deck_owner.id, old_rows, new_slides)
+                _lay_out_slide_rows(db, deck_owner.id, old_rows, layout, new_slides)
 
-            # 5. Deck columns, in the same transaction as the rows.
+            # 4. Deck columns, in the same transaction as the rows.
             deck.deck_spec_json = deck_spec
             deck.version = (deck.version or 0) + 1
             session.last_activity = now
             if session.id != deck_owner.id:
                 deck_owner.last_activity = now
 
-            # 6. Evidence; a refusal here rolls the whole shift back.
+            # 5. Evidence; a refusal here rolls the whole layout back.
             db.flush()
             record_shared_deck_mutation(
                 db,
@@ -603,13 +707,38 @@ class SlideWriter:
                 deck_owner=deck_owner,
                 deck=deck,
                 actor=mutation.actor,
-                operation="insert_slide",
+                operation=operation,
                 object_type="deck",
                 object_id=mutation.object_id,
             )
             return new_ids
 
 
+def layout_mutation_operation(layout: Sequence[Optional[int]], old_count: int) -> str:
+    """The ``MutationOperation`` that records *layout* over *old_count* current rows.
+
+    ``insert_slide`` when every old index is present in order and at least one
+    slot is ``None``; ``delete_slide`` when there is no ``None``, the kept
+    indices ascend and some are missing; ``reorder_slides`` when there is no
+    ``None``, every old index is present and they are out of order;
+    ``save_deck_slides`` for anything else (a mix).
+
+    Raises:
+        ValueError: the identity layout, which has nothing to write.
+    """
+    layout = list(layout)
+    kept = [index for index in layout if index is not None]
+    if len(kept) != len(layout):
+        return "insert_slide" if kept == list(range(old_count)) else "save_deck_slides"
+    if kept == list(range(old_count)):
+        raise ValueError("the identity layout changes nothing; there is nothing to write")
+    if all(a < b for a, b in zip(kept, kept[1:])):
+        return "delete_slide"
+    if len(kept) == old_count and set(kept) == set(range(old_count)):
+        return "reorder_slides"
+    return "save_deck_slides"
+
+
 # ------------------------------------------------------------------
 # Internal helpers
 # ------------------------------------------------------------------

{databricks_tellr_app-0.5.1.dev1 → databricks_tellr_app-0.5.1.dev3}/src/core/skills/architect.py

@@ -25,8 +25,10 @@ INSTRUCTIONS: str = (
     "PAYLOAD RULES:\n"
     "  build                  → deck_spec must be set\n"
     "  ask_data               → data_request must be set\n"
-    "  edit                   → target_positions must be a non-empty list AND "
-    "deck_spec must be set (an edit without deck_spec cannot be applied)\n"
+    "  edit                   → operations must be set for slide changes, and "
+    "deck_changes for a deck-level change the user asks for (one or both); "
+    "target_positions and deck_spec are not needed, except that re-describing the "
+    "deck as it stands returns the full deck_spec\n"
     "  confirm_design_contract → proposed_design_contract must be set; "
     "never set deck_spec until the user confirms\n"
     "  discuss                → message only; no payload required\n\n"
@@ -71,35 +73,69 @@ INSTRUCTIONS: str = (
     "content-bearing section whose frame fits; the exhibit replaces that "
     "section's body while its eyebrow, title and footer stay.\n\n"
     "EDITING (edit intent):\n"
-    "On an edit, start from current_deck_spec and return it in full as deck_spec. "
-    "Revise only what the user asked for on the target slides; keep every slide's "
-    "position and every other slide unchanged, except that adding a slide moves "
-    "each slide after it up by one position. Change deck-level fields only when "
-    "the user asks. Keep design_contract unchanged on an edit unless the user has "
-    "agreed to the contract you proposed with confirm_design_contract; otherwise "
-    "a change of design system or slide style still goes through "
-    "confirm_design_contract. Keep "
-    "resolved_data unchanged unless new data has been fetched for this edit.\n"
-    "Adding one or more new slides to an existing deck is an edit. Put each new "
-    "slide where the user asks. When the user gives no place, put it where it fits "
-    "the argument: before the slides that close the deck (a closing or "
-    "call-to-action slide), unless the new slide is itself a closing slide. When "
-    "the user asks for the new slide to come last, put it after the last slide, "
-    "even after a closing slide. Write the new slide's SlideSpec as for any other "
-    "slide, with slide_type and template_section_index decided by the VISUAL / "
-    "TEMPLATE BINDING rules, at the position it takes. Slides before it keep their "
-    "positions; every slide after it keeps every field exactly as in "
-    "current_deck_spec (purpose, content_brief, assumes, hands_off, "
-    "data_references, slide_type and template_section_index), and only its "
-    "position goes up by one. Do not change any other slide to reflect the new "
-    "one, not a neighbour's assumes or hands_off and not a slide that lists or "
-    "sums up the deck, and do not change any deck-level field, narrative_arc "
-    "included, unless the user asks for that change. target_positions lists the "
-    "positions, in the returned deck_spec, of every new slide and of every slide "
-    "the user asked to change. Say in message where the new slide went, by its "
-    "slide number in the revised deck.\n"
-    "Removing or reordering slides is not an edit: if the user asks for that, use "
-    "discuss and explain that it cannot be applied as an edit.\n\n"
+    "On an edit, return `operations` instead of deck_spec: the ordered list of changes "
+    "to make to current_deck_spec. They are applied together as one change, and nothing "
+    "else in the deck changes. The operations are:\n"
+    "  update  — `position` and `slides` with exactly one entry: that slide gets this "
+    "content and is rebuilt in place\n"
+    "  replace — `position` and `slides` with one or more entries: that slide becomes "
+    "these slides; the first takes its place and the rest follow it directly\n"
+    "  insert  — `after_position` and `slides` with one or more entries: new slides "
+    "directly after that slide, in list order; after_position -1 puts them at the start "
+    "of the deck\n"
+    "  delete  — `position`: that slide is removed, and nothing is rebuilt\n"
+    "  move    — `position` and `after_position`: that slide moves to directly after the "
+    "after_position slide (-1 = to the start); it is not rebuilt and its content does "
+    "not change\n"
+    "Each entry of `slides` is a SlideSpec without `position`, with slide_type and "
+    "template_section_index decided by the VISUAL / TEMPLATE BINDING rules. An update or "
+    "a replace describes the whole slide: start from the slide's entry in "
+    "current_deck_spec and revise only what the user asked for.\n"
+    "Every position and after_position is a position of current_deck_spec, the deck "
+    "before this edit, even for a slide that an earlier operation in the list shifts. "
+    "Give each slide the user asks about exactly one operation that does everything "
+    "asked of it: a slide can be the `position` of at most one operation. Slides placed "
+    "after the same slide go directly after it, in the order of their operations; "
+    "placed after a replaced slide, they follow all of its replacement slides; placed "
+    "after a moved slide, they follow it to its new place; placed after a deleted slide, "
+    "they fill its gap. Never move a slide after itself.\n"
+    "Changing what a slide says or shows is an update, even when the user says "
+    "\"replace\" about something on the slide. Expanding a slide into several slides, "
+    "splitting a slide, or replacing a slide with one or more new slides is a replace. "
+    "Rebuilding a slide without changing its content is an update with its current "
+    "content. Adding slides is an insert, removing a slide is a delete, and reordering "
+    "slides is a move.\n"
+    "Put each new slide where the user asks. When the user gives no place, put it where "
+    "it fits the argument: before the slides that close the deck (a closing or "
+    "call-to-action slide), unless the new slide is itself a closing slide. When the "
+    "user asks for the new slide to come last, put it after the last slide, even after "
+    "a closing slide.\n"
+    "Touch only the slides the user asks about: every other slide keeps its content "
+    "exactly, and only its number may change. Do not change any other slide to reflect "
+    "the edit, not a neighbour's assumes or hands_off and not a slide that lists or sums "
+    "up the deck, unless the user asks for that change.\n"
+    "Change deck-level fields only when the user asks, and then put only the changed "
+    "fields in `deck_changes` (title, audience, purpose, argument, call_to_action, "
+    "narrative_arc, design_contract, resolved_data); otherwise leave deck_changes unset. "
+    "Do not change narrative_arc to reflect an added, deleted or moved slide unless the "
+    "user asks for that change. Keep design_contract unchanged on an edit unless the "
+    "user has agreed to the contract you proposed with confirm_design_contract, and then "
+    "commit it in deck_changes.design_contract; otherwise a change of design system or "
+    "slide style still goes through confirm_design_contract. Keep resolved_data "
+    "unchanged unless new data has been fetched for this edit.\n"
+    "target_positions is not needed on an edit given as operations: the operations say "
+    "which slides are built.\n"
+    "Say in message what the edit will do: name each new or moved slide by its slide "
+    "number in the revised deck and each deleted slide by the number it had.\n"
+    "When the payload carries `rejected_edit`, your previous answer to this message "
+    "(`your_previous_answer`) was not applied and nothing in the deck changed; "
+    "`problems` lists every reason it was refused. Fix every listed problem and answer "
+    "again with the whole corrected answer. If a problem shows that the request cannot "
+    "be done as asked, use discuss and say why.\n"
+    "The one edit that returns deck_spec is a re-description: when the message asks you "
+    "to re-describe the deck as it now stands rather than change it, return the full "
+    "deck_spec describing every slide as it is, with target_positions listing its "
+    "positions and no operations.\n\n"
     "SLIDESPEC FIELDS (one per slide):\n"
     "  position: 0-indexed integer, unique within the deck\n"
     "  purpose: what this slide contributes to the narrative arc\n"
@@ -141,25 +177,24 @@ INSTRUCTIONS: str = (
     "and is never the number the user says. The payload's `slide_numbering` maps "
     "each slide of the current deck from its `slide_number` to its `position`, "
     "and `slide_references` lists the slides the user's latest message names by "
-    "number or ordinal, already resolved to `positions`. Take target_positions "
-    "from `slide_references` when the user's phrase was resolved; for a slide "
-    "number or ordinal it does not resolve, look the slide up in "
-    "`slide_numbering`. Never compute a position as the slide number minus one. "
-    "A reference with numbers in `out_of_range` names a slide this deck does not "
-    "have: do not edit; use discuss and say how many slides the deck has. When "
-    "the user names a slide by its content rather than its number, find it in "
-    "current_deck_spec. A reference says which slide the user means, not that "
+    "number or ordinal, already resolved to `positions`. Take each operation's "
+    "position and after_position from `slide_references` when the user's phrase "
+    "was resolved; for a slide number or ordinal it does not resolve, look the "
+    "slide up in `slide_numbering`. Never compute a position as the slide number "
+    "minus one. A reference with numbers in `out_of_range` names a slide this deck "
+    "does not have: do not edit; use discuss and say how many slides the deck has. "
+    "When the user names a slide by its content rather than its number, find it "
+    "in current_deck_spec. A reference says which slide the user means, not that "
     "they want it changed: decide the intent from what the user asks for.\n"
-    "The exception to taking target_positions from `slide_references` is a request "
-    "to add a slide. Read every slide number in it against `slide_numbering`, the "
-    "deck before the new slide goes in. A slide the user names to say where the new "
-    "slide goes is its anchor, not a target: a new slide placed after the named "
-    "slide takes the position after it, and a new slide placed before the named "
-    "slide, or given the named slide's number, takes the named slide's position "
-    "while the named slide moves up by one. A named slide the user also asks to "
-    "change is a target at its position in the returned deck_spec, which is one "
-    "higher than in `slide_references` when it comes after the new slide.\n"
-    "In `message` only, speak about slides 1-indexed, matching the UI. "
-    "`position` and `target_positions` stay 0-indexed.\n\n"
+    "Read every slide number in an edit against `slide_numbering`, the deck before "
+    "the edit, even when the same message also adds, deletes or moves slides. A "
+    "slide the user names to say where a new or moved slide goes is its anchor, not "
+    "a slide to change. A slide placed after the named slide takes the named "
+    "slide's position as after_position. A slide placed before the named slide, or "
+    "given the named slide's number, takes as after_position the position of the "
+    "slide just before the named one in `slide_numbering`, or -1 when the named "
+    "slide is the first.\n"
+    "In `message` only, speak about slides 1-indexed, matching the UI. `position`, "
+    "`after_position` and `target_positions` stay 0-indexed.\n\n"
     "Return an ArchitectOutput.  Do not include prose outside the structured output."
 )