gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/schema/slack.py

@@ -0,0 +1,757 @@
+"""Deterministic Slack evidence mapping and executable bundle construction.
+
+Capture owns authorization and verified evidence bytes. This module never contacts
+Slack, reads credentials, downloads files, guesses missing targets, or prunes rows.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+import hashlib
+import json
+from pathlib import Path
+import shutil
+import tempfile
+
+from .compiler import Contract, check_bundle
+from .scaffold import init_bundle
+from .store import SQLiteStore
+from .validation import encoded, fail, read_json
+from ._slack_fidelity import fidelity_report, load_capabilities, slack_template_digest
+from ._slack_scenario import write_scenario
+
+FORMAT = "gateway-slack-evidence/1"
+MAPPING = {"id": "slack-evidence", "version": "1"}
+
+
+def _merge(old, patch):
+    if isinstance(old, dict) and isinstance(patch, dict):
+        return {**deepcopy(old), **{k: _merge(old.get(k), v) for k, v in patch.items()}}
+    return deepcopy(patch)
+
+
+def _identity(contract, entity, value):
+    try:
+        return {field: value[field] for field in contract.entities[entity]["primary_key"]}
+    except (KeyError, TypeError):
+        fail("slack_evidence", "Observed record is missing a natural key", "/evidence", entity=entity)
+
+
+def _envelope(evidence):
+    if not isinstance(evidence, dict) or evidence.get("format") != FORMAT:
+        fail("slack_evidence", "Expected gateway-slack-evidence/1", "/evidence/format")
+    workspace = evidence.get("workspace")
+    principal = evidence.get("principal")
+    if not isinstance(workspace, dict) or not isinstance(workspace.get("id"), str) or not workspace["id"]:
+        fail("slack_evidence", "A captured workspace identity is required", "/evidence/workspace")
+    if not isinstance(principal, dict) or not isinstance(principal.get("user_id"), str) or not principal["user_id"]:
+        fail("slack_evidence", "A captured principal identity is required", "/evidence/principal")
+    if not isinstance(evidence.get("observations"), list):
+        fail("slack_evidence", "Observations must be an array", "/evidence/observations")
+    return workspace, principal
+
+
+def map_slack_evidence(
+    evidence: dict, contract: Contract, *, existing=None, batch_id: str | None = None, diagnostics: dict | None = None
+) -> dict:
+    """Map safe Slack response projections to one atomic batch with explicit patches.
+
+    ``existing`` is an optional validated store used when refreshing. Missing
+    properties are untouched; explicit nulls/empty collections remain observed
+    values. Partial pages never imply deletions. All closure is checked by store.
+    Sources must refer to capture-owned, digest-verified bytes (or synthetic bytes).
+    """
+    workspace, principal = _envelope(evidence)
+    wid = workspace["id"]
+    records: dict[tuple[str, bytes], dict] = {}
+    deletions = []
+    removals = {}
+    diagnostics = diagnostics if diagnostics is not None else {}
+    diagnostics.setdefault("unmapped_fields", [])
+
+    def remove_observed_collection(entity, where, retained, source):
+        """Explicit nested collection values can clear their own keyed rows.
+
+        This is distinct from absent data or a partial top-level API page. The
+        caller names each exact association collection represented by the value.
+        """
+        if existing is None:
+            return
+        for row in existing.list(entity):
+            if row.get("workspace_id") != wid or any(row.get(k) != v for k, v in where.items()):
+                continue
+            key = _identity(contract, entity, row)
+            token = entity, encoded(key)
+            if token not in retained:
+                removals[token] = {
+                    "op": "delete",
+                    "entity": entity,
+                    "key": key,
+                    "source": {
+                        "record": "slack:observed-collection:" + hashlib.sha256(encoded(key)).hexdigest(),
+                        "evidence": [source],
+                    },
+                }
+
+    def project(entity, value):
+        if not isinstance(value, dict):
+            fail("slack_evidence", "Expected an object observation", "/evidence", entity=entity)
+        allowed = contract.entities[entity]["schema"]["properties"]
+        normalized = {
+            "slack_users": {"presence"},
+            "slack_channels": {
+                "is_member",
+                "is_open",
+                "is_starred",
+                "is_read_only",
+                "is_thread_only",
+                "user",
+                "last_read",
+                "unread_count",
+                "unread_count_display",
+                "latest",
+            },
+            "slack_messages": {"thread_ts", "reactions", "files", "is_starred"},
+            "slack_files": {"shares", "channels", "groups", "ims"},
+            "slack_file_shares": {"ts", "thread_ts", "position"},
+            "slack_presence": {"ok"},
+            "slack_usergroups": {"users"},
+        }
+        for field in sorted(set(value) - set(allowed) - normalized.get(entity, set())):
+            marker = entity + "." + field
+            if marker not in diagnostics["unmapped_fields"]:
+                diagnostics["unmapped_fields"].append(marker)
+        return {k: deepcopy(v) for k, v in value.items() if k in allowed}
+
+    def observe(entity, value, source):
+        value = project(entity, value)
+        key = _identity(contract, entity, value)
+        token = entity, encoded(key)
+        if not isinstance(source, dict) or set(source) != {"reference", "digest"}:
+            fail("slack_evidence", "Each observation requires an evidence reference and digest", "/evidence/source")
+        if token not in records:
+            records[token] = {"entity": entity, "key": key, "value": value, "evidence": []}
+        else:
+            records[token]["value"] = _merge(records[token]["value"], value)
+        if source not in records[token]["evidence"]:
+            records[token]["evidence"].append(deepcopy(source))
+
+    # The containing workspace is provider-supplied context, never an actor's home team.
+    root_source = evidence.get("source")
+    if not root_source and evidence["observations"]:
+        root_source = evidence["observations"][0].get("source")
+    if not root_source:
+        fail("slack_evidence", "Evidence source metadata is required", "/evidence/source")
+    observe("slack_workspaces", workspace, root_source)
+
+    def user(value, source):
+        normalized = {**value, "workspace_id": wid}
+        profile = normalized.get("profile")
+        if isinstance(profile, dict) and "fields" in profile:
+            profile = dict(profile)
+            fields = profile.pop("fields")
+            profile["fields_state"] = "null" if fields is None else "present"
+            normalized["profile"] = profile
+            if fields is not None:
+                if not isinstance(fields, dict):
+                    fail("slack_evidence", "Profile fields must be an object or null", "/evidence/profile/fields")
+                for field_id, field in fields.items():
+                    observe(
+                        "slack_user_profile_fields",
+                        {"workspace_id": wid, "user_id": value["id"], "field_id": field_id, **field},
+                        source,
+                    )
+            retained = {
+                ("slack_user_profile_fields", encoded({"workspace_id": wid, "user_id": value["id"], "field_id": fid}))
+                for fid in (fields or {})
+            }
+            remove_observed_collection("slack_user_profile_fields", {"user_id": value["id"]}, retained, source)
+        observe("slack_users", normalized, source)
+
+    def channel(value, source):
+        observe("slack_channels", {**value, "workspace_id": wid}, source)
+        state = {"workspace_id": wid, "channel_id": value["id"], "user_id": principal["user_id"]}
+        fields = contract.entities["slack_conversation_states"]["schema"]["properties"]
+        for k in fields:
+            if k in value and k not in ("workspace_id", "channel_id", "user_id"):
+                state[k] = value[k]
+        if "user" in value:
+            state["counterpart_user_id"] = value["user"]
+        if len(state) > 3:
+            observe("slack_conversation_states", state, source)
+        if value.get("is_member") is True:
+            observe(
+                "slack_memberships",
+                {"workspace_id": wid, "channel_id": value["id"], "user_id": principal["user_id"]},
+                source,
+            )
+        elif value.get("is_member") is False:
+            remove_observed_collection(
+                "slack_memberships", {"channel_id": value["id"], "user_id": principal["user_id"]}, set(), source
+            )
+
+    def file_record(value, source):
+        if (
+            not all(k in value for k in ("id", "mode", "mimetype", "size"))
+            or value.get("mode") in ("tombstone", "file_access")
+            or value.get("file_access") == "check_file_info"
+        ):
+            return False
+        observe("slack_files", {**value, "workspace_id": wid}, source)
+        for name in ("channels", "groups", "ims"):
+            for cid in value.get(name, []):
+                observe(
+                    "slack_file_channel_observations",
+                    {"workspace_id": wid, "file_id": value["id"], "channel_id": cid, "kind": name},
+                    source,
+                )
+        return True
+
+    def message(value, cid, source):
+        if not cid:
+            fail("slack_evidence", "Message observation requires channel context", "/evidence/context/channel_id")
+        observe("slack_messages", {**value, "workspace_id": wid, "channel_id": cid}, source)
+        ts = value["ts"]
+        if value.get("thread_ts") and value["thread_ts"] != ts:
+            observe(
+                "slack_message_threads",
+                {"workspace_id": wid, "channel_id": cid, "reply_ts": ts, "parent_ts": value["thread_ts"]},
+                source,
+            )
+        for reaction in value.get("reactions", []):
+            base = {"workspace_id": wid, "channel_id": cid, "message_ts": ts, "name": reaction["name"]}
+            observe("slack_reaction_summaries", {**base, "count": reaction["count"]}, source)
+            for actor in reaction.get("users", []):
+                observe("slack_reaction_users", {**base, "user_id": actor}, source)
+        if "reactions" in value and not value["reactions"]:
+            for entity in ("slack_reaction_users", "slack_reaction_summaries"):
+                remove_observed_collection(entity, {"channel_id": cid, "message_ts": ts}, set(), source)
+        for position, item in enumerate(value.get("files", [])):
+            base = {
+                "workspace_id": wid,
+                "channel_id": cid,
+                "message_ts": ts,
+                "file_id": item["id"],
+                "position": position,
+            }
+            if file_record(item, source):
+                observe("slack_message_files", base, source)
+                for visibility, channels in item.get("shares", {}).items():
+                    for share_channel, shares in channels.items():
+                        for share in shares:
+                            # Share metadata has structural meaning only for this observed occurrence.
+                            if share_channel == cid and share.get("ts") == ts:
+                                observe(
+                                    "slack_file_shares",
+                                    (
+                                        {
+                                            **base,
+                                            **share,
+                                            "visibility": visibility,
+                                            "observed_thread_ts": share.get("thread_ts"),
+                                        }
+                                        if "thread_ts" in share
+                                        else {**base, **share, "visibility": visibility}
+                                    ),
+                                    source,
+                                )
+            else:
+                discriminator = {k: item[k] for k in ("file_access", "mode") if k in item}
+                if item.get("file_access") == "check_file_info":
+                    discriminator = {"file_access": "check_file_info"}
+                if not discriminator:
+                    # No canonical full shape or explicit unavailable discriminator: refuse invention.
+                    fail(
+                        "slack_evidence", "Incomplete file projection lacks an access discriminator", "/evidence/files"
+                    )
+                observe("slack_unavailable_message_files", {**base, "reference": discriminator}, source)
+        if "files" in value:
+            # A message's explicitly supplied attachment collection is one value,
+            # unlike an API page of messages. Retain file metadata as historical
+            # observations but replace the occurrence's full/unavailable links.
+            for entity in ("slack_file_shares", "slack_message_files", "slack_unavailable_message_files"):
+                retained = {
+                    token
+                    for token, record in records.items()
+                    if token[0] == entity
+                    and record["value"].get("channel_id") == cid
+                    and record["value"].get("message_ts") == ts
+                }
+                if entity == "slack_file_shares":
+                    retained |= {
+                        ("slack_file_shares", token[1])
+                        for token, record in records.items()
+                        if token[0] == "slack_message_files"
+                        and record["value"].get("channel_id") == cid
+                        and record["value"].get("message_ts") == ts
+                    }
+                remove_observed_collection(entity, {"channel_id": cid, "message_ts": ts}, retained, source)
+        if "is_starred" in value:
+            observe(
+                "slack_message_user_states",
+                {
+                    "workspace_id": wid,
+                    "channel_id": cid,
+                    "message_ts": ts,
+                    "user_id": principal["user_id"],
+                    "is_starred": value["is_starred"],
+                },
+                source,
+            )
+
+    for observation in evidence["observations"]:
+        if not isinstance(observation, dict):
+            fail("slack_evidence", "Observation must be an object", "/evidence/observations")
+        method = observation.get("method")
+        context = observation.get("context", {})
+        data = observation.get("data")
+        source = observation.get("source", evidence.get("source"))
+        if not isinstance(data, dict) or data.get("ok") is not True:
+            fail(
+                "slack_evidence", "Only successful projected observations can be mapped", "/evidence/observations/data"
+            )
+        cid = context.get("channel_id")
+        if method == "auth.test":
+            if data.get("team_id") != wid or data.get("user_id") != principal["user_id"]:
+                fail("slack_evidence", "Capture principal/workspace identity mismatch", "/evidence/observations/data")
+        elif method == "team.info":
+            if data["team"]["id"] != wid:
+                fail("slack_evidence", "Workspace observation identity mismatch", "/evidence/observations/data")
+            observe("slack_workspaces", data["team"], source)
+        elif method == "users.list":
+            for value in data["members"]:
+                user(value, source)
+        elif method == "users.info":
+            user(data["user"], source)
+        elif method == "conversations.list":
+            for value in data["channels"]:
+                channel(value, source)
+        elif method == "conversations.info":
+            channel(data["channel"], source)
+        elif method == "conversations.members":
+            for actor in data["members"]:
+                observe("slack_memberships", {"workspace_id": wid, "channel_id": cid, "user_id": actor}, source)
+        elif method in ("conversations.history", "conversations.replies"):
+            for value in data["messages"]:
+                message(value, cid, source)
+        elif method == "files.info":
+            if not file_record(data["file"], source):
+                fail("slack_evidence", "Standalone incomplete file cannot form a canonical file row", "/evidence/files")
+        elif method == "pins.list":
+            for item in data["items"]:
+                if item.get("type") != "message":
+                    continue
+                message(item["message"], cid, source)
+                observe(
+                    "slack_pins",
+                    {
+                        "workspace_id": wid,
+                        "channel_id": cid,
+                        "message_ts": item["message"]["ts"],
+                        **{k: item[k] for k in ("created", "created_by") if k in item},
+                    },
+                    source,
+                )
+        elif method == "bookmarks.list":
+            for value in data["bookmarks"]:
+                observe("slack_bookmarks", {**value, "workspace_id": wid, "channel_id": cid}, source)
+        elif method == "users.getPresence":
+            observe("slack_presence", {**data, "workspace_id": wid, "user_id": context["user_id"]}, source)
+        elif method == "usergroups.list":
+            for value in data["usergroups"]:
+                observe(
+                    "slack_usergroups",
+                    {**value, "workspace_id": wid, **({"users_state": "present"} if "users" in value else {})},
+                    source,
+                )
+                for actor in value.get("users", []):
+                    observe(
+                        "slack_usergroup_memberships",
+                        {"workspace_id": wid, "usergroup_id": value["id"], "user_id": actor},
+                        source,
+                    )
+        elif method == "message.deleted":
+            # Only explicit captured deletion events authorize deletion. History
+            # absence, access loss and complete-page claims never enter this path.
+            if existing is None or not cid or not isinstance(data.get("deleted_ts"), str):
+                fail(
+                    "slack_evidence",
+                    "A deletion needs existing state, channel and exact deleted_ts",
+                    "/evidence/deletion",
+                )
+            if not isinstance(source, dict) or set(source) != {"reference", "digest"}:
+                fail("slack_evidence", "Deletion evidence source is required", "/evidence/deletion/source")
+            deletions.append((cid, data["deleted_ts"], source))
+        else:
+            fail("slack_evidence", "Unsupported captured method", "/evidence/observations/method")
+
+    mutations = []
+    for token, removal in sorted(removals.items()):
+        if token in records:
+            fail(
+                "slack_evidence",
+                "Conflicting complete collection observations",
+                "/evidence/observations",
+                entity=token[0],
+            )
+        mutations.append(removal)
+    for (entity, _), record in sorted(records.items()):
+        prior = existing.get(entity, record["key"]) if existing is not None else None
+        value = _merge(prior, record["value"]) if prior else record["value"]
+        source = {
+            "record": "slack:" + entity + ":" + hashlib.sha256(encoded(record["key"])).hexdigest(),
+            "evidence": sorted(record["evidence"], key=lambda e: (e["reference"], e["digest"])),
+        }
+        mutation = {"op": "update" if prior else "insert", "entity": entity, "value": value, "source": source}
+        if prior:
+            mutation["key"] = record["key"]
+        mutations.append(mutation)
+    deleted_keys = set()
+    for cid, ts, evidence_source in sorted(deletions, key=lambda row: (row[0], row[1])):
+        for entity in (
+            "slack_reaction_users",
+            "slack_reaction_summaries",
+            "slack_message_user_states",
+            "slack_file_shares",
+            "slack_message_files",
+            "slack_unavailable_message_files",
+            "slack_pins",
+            "slack_message_threads",
+            "slack_messages",
+        ):
+            field = (
+                "ts"
+                if entity == "slack_messages"
+                else "reply_ts" if entity == "slack_message_threads" else "message_ts"
+            )
+            for row in existing.list(entity):
+                if row.get("workspace_id") != wid or row.get("channel_id") != cid or row.get(field) != ts:
+                    continue
+                key = _identity(contract, entity, row)
+                token = entity, encoded(key)
+                if token in deleted_keys:
+                    continue
+                if token in records:
+                    fail(
+                        "slack_evidence",
+                        "Capture both updates and deletes the same record",
+                        "/evidence/deletion",
+                        entity=entity,
+                    )
+                deleted_keys.add(token)
+                mutations.append(
+                    {
+                        "op": "delete",
+                        "entity": entity,
+                        "key": key,
+                        "source": {
+                            "record": "slack:message.deleted:" + hashlib.sha256(encoded(key)).hexdigest(),
+                            "evidence": [evidence_source],
+                        },
+                    }
+                )
+    return {
+        "id": batch_id or "slack." + hashlib.sha256(encoded(evidence)).hexdigest(),
+        "target": contract.target,
+        "mapping": MAPPING,
+        "coverage": "partial",
+        "mutations": mutations,
+    }
+
+
+def synthetic_slack_evidence() -> dict:
+    """An invented workspace with members, threads, rich content and file variants."""
+    observations = []
+
+    def add(method, data, **context):
+        digest = hashlib.sha256(encoded({"method": method, "context": context, "data": data})).hexdigest()
+        observations.append(
+            {
+                "method": method,
+                "context": context,
+                "data": {"ok": True, **data},
+                "source": {"reference": "synthetic:slack:" + digest, "digest": digest},
+            }
+        )
+
+    add("auth.test", {"team_id": "TSYNTH", "user_id": "UAGENT"})
+    add(
+        "users.list",
+        {
+            "members": [
+                {
+                    "id": "UAGENT",
+                    "name": "gateway-helper",
+                    "real_name": "Gateway Helper",
+                    "is_bot": False,
+                    "deleted": False,
+                    "profile": {"display_name": "Helper", "email": None},
+                },
+                {
+                    "id": "UALICE",
+                    "name": "alice",
+                    "real_name": "Alice Rivers",
+                    "deleted": False,
+                    "profile": {
+                        "display_name": "Alice",
+                        "title": "Release owner",
+                        "fields": {"XROLE": {"value": "Engineering", "alt": ""}},
+                    },
+                },
+                {"id": "UBOB", "name": "bob", "real_name": "Bob Chen", "deleted": False},
+                {"id": "UFORMER", "name": "former", "deleted": True},
+                {"id": "UBOT", "name": "build-bot", "is_bot": True, "deleted": False},
+            ]
+        },
+    )
+    channels = [
+        {
+            "id": "CGENERAL",
+            "name": "release-handoff",
+            "is_channel": True,
+            "is_private": False,
+            "is_archived": False,
+            "num_members": 3,
+            "is_member": True,
+            "topic": {"value": "Release readiness and ownership", "creator": "UALICE", "last_set": 1700000000},
+        },
+        {
+            "id": "CPUBLIC",
+            "name": "engineering",
+            "is_channel": True,
+            "is_private": False,
+            "is_archived": False,
+            "is_member": False,
+        },
+        {
+            "id": "CPRIVATE",
+            "name": "incident-room",
+            "is_channel": True,
+            "is_private": True,
+            "is_archived": False,
+            "is_member": True,
+        },
+        {
+            "id": "CSECRET",
+            "name": "restricted",
+            "is_channel": True,
+            "is_private": True,
+            "is_archived": False,
+            "is_member": False,
+        },
+        {
+            "id": "CARCHIVED",
+            "name": "previous-release",
+            "is_channel": True,
+            "is_private": False,
+            "is_archived": True,
+            "is_member": True,
+        },
+        {"id": "DPAIR", "is_im": True, "is_private": True, "is_member": True, "user": "UALICE"},
+        {"id": "GTEAM", "is_mpim": True, "is_private": True, "is_member": True},
+    ]
+    add("conversations.list", {"channels": channels})
+    for cid in ("CGENERAL", "CPRIVATE", "CARCHIVED", "DPAIR", "GTEAM"):
+        add(
+            "conversations.members",
+            {"members": ["UAGENT", "UALICE", "UBOB"] if cid == "CGENERAL" else ["UAGENT", "UALICE"]},
+            channel_id=cid,
+        )
+    add("conversations.members", {"members": ["UALICE", "UBOB"]}, channel_id="CSECRET")
+    parent = "1700000000.000000000000000001"
+    add(
+        "conversations.history",
+        {
+            "messages": [
+                {
+                    "ts": parent,
+                    "type": "message",
+                    "user": "UALICE",
+                    "text": "Please review the release checklist, acknowledge it, and reply here with the handoff owner and next update.",
+                    "reply_count": 1,
+                    "blocks": [
+                        {
+                            "type": "section",
+                            "text": {
+                                "type": "mrkdwn",
+                                "text": "*Release handoff* — owner Alice; next update 17:00 UTC.",
+                            },
+                        }
+                    ],
+                    "reactions": [{"name": "eyes", "count": 1, "users": ["UBOB"]}],
+                    "files": [
+                        {
+                            "id": "FCHECKLIST",
+                            "name": "release-checklist.md",
+                            "title": "Release checklist",
+                            "mode": "hosted",
+                            "mimetype": "text/markdown",
+                            "size": 512,
+                            "user": "UALICE",
+                            "is_public": False,
+                        }
+                    ],
+                },
+                {
+                    "ts": "1700000002.000001",
+                    "type": "message",
+                    "user": "UBOT",
+                    "bot_id": "BPIPELINE",
+                    "text": "Build passed; deployment awaits review.",
+                    "files": [{"id": "FRESTRICTED", "file_access": "check_file_info"}],
+                },
+            ]
+        },
+        channel_id="CGENERAL",
+    )
+    add(
+        "conversations.replies",
+        {
+            "messages": [
+                {"ts": parent, "type": "message", "user": "UALICE", "thread_ts": parent, "reply_count": 1},
+                {
+                    "ts": "1700000000.000000000000000002",
+                    "thread_ts": parent,
+                    "type": "message",
+                    "user": "UBOB",
+                    "text": "Tests complete. Please confirm the final owner and next update.",
+                },
+            ]
+        },
+        channel_id="CGENERAL",
+        thread_ts=parent,
+    )
+    add(
+        "bookmarks.list",
+        {
+            "bookmarks": [
+                {
+                    "id": "BMRELEASE",
+                    "type": "link",
+                    "title": "Release checklist",
+                    "rank": "0",
+                    "link": "https://example.invalid/release-checklist",
+                }
+            ]
+        },
+        channel_id="CGENERAL",
+    )
+    add("users.getPresence", {"presence": "active"}, user_id="UALICE")
+    add(
+        "usergroups.list",
+        {
+            "usergroups": [
+                {
+                    "id": "SRELEASE",
+                    "name": "Release team",
+                    "handle": "release",
+                    "users": ["UALICE", "UBOB"],
+                    "user_count": 2,
+                }
+            ]
+        },
+    )
+    return {
+        "format": FORMAT,
+        "synthetic": True,
+        "workspace": {"id": "TSYNTH", "name": "Synthetic Release Team", "domain": "synthetic-release"},
+        "principal": {"user_id": "UAGENT"},
+        "observations": observations,
+        "coverage": {"complete": False, "reasons": ["Invented fixture; no live workspace evidence."]},
+    }
+
+
+def build_slack_bundle(destination: str | Path, *, evidence: dict | None = None, name: str | None = None) -> Contract:
+    """Create a populated executable Slack bundle in a new/empty directory."""
+    evidence = synthetic_slack_evidence() if evidence is None else evidence
+    workspace, principal = _envelope(evidence)
+    destination = Path(destination)
+    contract = init_bundle(destination, connector="slack", name=name or "slack-world")
+    try:
+        diagnostics = {}
+        batch = map_slack_evidence(evidence, contract, diagnostics=diagnostics)
+        with tempfile.TemporaryDirectory(prefix="gateway-slack-") as temporary:
+            with SQLiteStore.create(Path(temporary) / "state.sqlite", contract) as store:
+                store.apply_batch(batch)
+                if store.get("slack_users", {"workspace_id": workspace["id"], "id": principal["user_id"]}) is None:
+                    fail("slack_evidence", "The authenticated principal was not captured", "/evidence/principal")
+                store.audit()
+        (destination / "data/initial.json").write_bytes(encoded(batch))
+        (destination / "tools/slack-principal.json").write_bytes(
+            encoded({"workspace_id": workspace["id"], "user_id": principal["user_id"]})
+        )
+        (destination / "fidelity.json").write_bytes(
+            encoded(fidelity_report(contract, evidence, batch, diagnostics, mapping=MAPPING))
+        )
+        (destination / "capabilities.json").write_bytes(encoded(load_capabilities()))
+        write_scenario(destination, evidence, batch, entities=contract.entities)
+        (destination / "slack-imports.json").write_bytes(
+            encoded({batch["id"]: hashlib.sha256(encoded(evidence)).hexdigest()})
+        )
+        check_bundle(destination)
+        return contract
+    except BaseException:
+        shutil.rmtree(destination)
+        raise
+
+
+def refresh_slack_bundle(destination: str | Path, evidence: dict | None = None, *, batch_id: str | None = None) -> dict:
+    """Validate then append one refresh batch; preserve original batch and lineage.
+
+    Call this only on an isolated copy while constructing a new immutable version.
+    The publisher owns expected-parent CAS and immutable version promotion.
+    """
+    destination = Path(destination)
+    evidence = synthetic_slack_evidence() if evidence is None else evidence
+    workspace, principal = _envelope(evidence)
+    pinned = read_json(destination / "tools/slack-principal.json")
+    if pinned != {"workspace_id": workspace["id"], "user_id": principal["user_id"]}:
+        fail("slack_evidence", "Refresh cannot change the bound workspace or principal", "/evidence/principal")
+    contract = check_bundle(destination)
+    previous_report = read_json(destination / "fidelity.json")
+    if previous_report.get("template_digest") != slack_template_digest():
+        fail(
+            "slack_template_mismatch",
+            "Refresh requires the original template package; create a new world with the current template",
+            "/fidelity/template_digest",
+        )
+    digest = hashlib.sha256(encoded(evidence)).hexdigest()
+    batch_id = batch_id or "slack." + digest
+    imports = read_json(destination / "slack-imports.json")
+    if batch_id in imports:
+        if imports[batch_id] != digest:
+            fail("idempotency_conflict", "Refresh ID was used for different evidence", "/evidence")
+        return {"status": "already_applied", "batch": batch_id, "applied": 0}
+    batches = sorted((destination / "data/batches").glob("*.json"))
+    with tempfile.TemporaryDirectory(prefix="gateway-slack-refresh-") as temporary:
+        with SQLiteStore.create(Path(temporary) / "state.sqlite", contract) as store:
+            store.apply_batch(read_json(destination / "data/initial.json"))
+            for path in batches:
+                store.apply_batch(read_json(path))
+            diagnostics = {}
+            batch = map_slack_evidence(evidence, contract, existing=store, batch_id=batch_id, diagnostics=diagnostics)
+            result = store.apply_batch(batch)
+            store.audit()
+            state = {
+                "mutations": [
+                    {"op": "insert", "entity": entity, "value": value}
+                    for entity in sorted(contract.entities)
+                    for value in store.list(entity)
+                ]
+            }
+    target = (
+        destination
+        / "data/batches"
+        / f"{len(batches) + 1:06d}-{hashlib.sha256(batch_id.encode()).hexdigest()[:16]}.json"
+    )
+    target.parent.mkdir(exist_ok=True)
+    temporary = target.with_suffix(".pending")
+    temporary.write_bytes(encoded(batch))
+    temporary.replace(target)
+    imports[batch_id] = digest
+    (destination / "slack-imports.json").write_bytes(encoded(imports))
+    (destination / "fidelity.json").write_bytes(
+        encoded(fidelity_report(contract, evidence, batch, diagnostics, mapping=MAPPING))
+    )
+    write_scenario(destination, evidence, state, entities=contract.entities)
+    return result