taskwire 0.1.0__py3-none-any.whl

taskwire/contrib/schema.py

@@ -0,0 +1,204 @@
+"""Pydantic mirrors of the wire documents (§3), for the viewset layer only.
+
+Imports pydantic; nothing in `taskwire/` outside `contrib` may (TW-CORE-006). **The core stays
+dependency-free**, and that is not a stylistic preference: `pip install taskwire` has to work in a
+bare script, and the dataclasses in `models.py` are the normative shapes. These are a projection of
+them onto a schema language, kept here so the projection can never become the definition.
+
+## Why mirror at all
+
+`fastapi-viewsets` types a viewset over a `BaseModel` - it introspects fields to build the OpenAPI
+schema, to derive filter models, and to strip the pk from create bodies. Handing it a dataclass
+would work for none of that, and the schema is the point: it is what the FE proxy validates itself
+against, and what a reader of `/docs` sees.
+
+## The one deliberate difference from `to_dict()`
+
+`to_dict()` **omits** an absent optional field; these models **emit it as null**. Both are legal on
+the wire and parse identically, because TW-CORE-010 requires absent and null to be indistinguishable
+to a reader - a rule written for exactly this kind of second producer. `schema_test.py` asserts the
+equivalence by feeding every conformance fixture through both paths.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from ..models import DialogState, ProgressState, WIRE_VERSION
+
+
+class Text(BaseModel):
+    """TW-TXT-001. Any subset of the three is valid; a frontend with a catalogue uses `key`."""
+
+    key: str | None = None
+    params: dict[str, Any] | None = None
+    text: str | None = None
+
+
+class Error(BaseModel):
+    """TW-PROG-005. No stack trace, deliberately - this document reaches a browser."""
+
+    code: str
+    message: Text = Field(default_factory=Text)
+    retryable: bool = False
+
+
+class ResultRef(BaseModel):
+    """A pointer to an artefact the **application** owns (TW-RES-007). taskwire stores it, never serves it."""
+
+    href: str
+    mime: str | None = None
+    bytes: int | None = None
+    expires_at: str | None = None
+
+
+class Result(BaseModel):
+    """TW-RES-002. `kind` names the component that collects this; taskwire never validates the set."""
+
+    kind: str
+    params: dict[str, Any] | None = None
+    label: Text | None = None
+    value: Any = None
+    ref: ResultRef | None = None
+
+
+class Button(BaseModel):
+    """A choice on a dialog. There is no `default` flag - a default button's only use is answering a
+    timeout, and there are no timeouts (TW-DLG-005)."""
+
+    id: str
+    label: Text | None = None
+    style: str | None = None
+
+
+class Input(BaseModel):
+    """A value collected alongside the choice. `type` is one of TW-DLG-004's four and nothing more."""
+
+    name: str
+    type: str = "string"
+    required: bool = False
+    label: Text | None = None
+
+
+class DialogReply(BaseModel):
+    """The body of an answer: which button, and the values collected with it."""
+
+    button: str
+    values: dict[str, Any] = Field(default_factory=dict)
+
+
+class DialogRequest(BaseModel):
+    """One asking. `id` is *this asking*, `dialog_id` is *which question* (TW-DLG-001).
+
+    Only `id` is ever a key or a path segment. Keying by `dialog_id` would let two concurrent
+    operations rendering the same component answer each other's question (TW-DLG-002).
+    """
+
+    id: str
+    dialog_id: str
+    buttons: list[Button] = Field(default_factory=list)
+    inputs: list[Input] = Field(default_factory=list)
+    params: dict[str, Any] | None = None
+    state: DialogState = DialogState.OPEN
+    created_at: str
+    reply: DialogReply | None = None
+
+
+class Progress(BaseModel):
+    """§3.2, the one document per operation.
+
+    `state` is never written by a caller - it is derived from lifecycle events and nothing else
+    (TW-PROG-012) - and `result_kind` / `origin_session` / `origin_connection` are fixed at the
+    opening write and never rewritten (TW-PROG-006).
+    """
+
+    state: ProgressState = ProgressState.QUEUED
+    percent: float | None = None
+    title: Text | None = None
+    label: Text | None = None
+    icon: str | None = None
+    data: dict[str, Any] = Field(default_factory=dict)
+    error: Error | None = None
+    result: Result | None = None
+    result_kind: str | None = None
+    origin_session: str = ""
+    origin_connection: str | None = None
+    created_at: str
+    updated_at: str
+
+
+class Snapshot(BaseModel):
+    """§3.6. The complete current state of one operation - which is what makes reconnect a single GET."""
+
+    v: int = WIRE_VERSION
+    token: str
+    rev: int
+    progress: Progress
+    dialogs: list[DialogRequest] = Field(default_factory=list)
+    cancel_requested: bool = False
+    server_time: str
+    poll_after_ms: int = 5000
+
+
+class OperationSummary(BaseModel):
+    """§3.7. One register row: the whole snapshot, plus what a list view needs lifted out of it.
+
+    `token` is the pk the viewset is keyed on. That is not a convenience - the token IS the identity
+    of an operation, and there is no other key anywhere in the system (TW-KEY-001).
+    """
+
+    token: str
+    snapshot: Snapshot
+    result_kind: str | None = None
+    origin_session: str = ""
+    result: Result | None = None
+    needs_attention: bool = False
+    progress_delivery: bool = True
+
+
+class Aggregate(BaseModel):
+    """§3.8a. Counts and a dominated state.
+
+    **There is no `percent` and no rule may add one** (TW-REG-011). Two operations' self-reported
+    percentages are not commensurable - one is 40 % through a row count, the other through a byte
+    count - so any figure derived across them is invented. The field is absent from the wire rather
+    than null on it, which is why it is absent from this model too.
+    """
+
+    state: ProgressState
+    title: Text = Field(default_factory=lambda: Text(key="taskwire.aggregate.title"))
+    data: dict[str, int] = Field(default_factory=dict)
+    label: Text | None = None
+    updated_at: str
+
+
+class Register(BaseModel):
+    """§3.8. Every shared operation of one namespace, sorted, with its aggregate.
+
+    Returned by `GET {prefix}` rather than as a `list[OperationSummary]`: this document carries
+    `poll_after_ms`, which TW-REST-014 makes binding on the client's next poll, and the aggregate
+    computed over the same read.
+    """
+
+    v: int = WIRE_VERSION
+    operations: list[OperationSummary] = Field(default_factory=list)
+    aggregate: Aggregate | None = None
+    server_time: str
+    poll_after_ms: int = 5000
+
+
+class Accepted(BaseModel):
+    """TW-CANCEL-003: a cancel request is an **acknowledgement**, never a completion.
+
+    The operation stops when its own code next looks, which may be never - taskwire does not revoke
+    tasks, signal threads or interrupt blocking code (TW-CANCEL-009). Answering `202` with this
+    rather than `200` with a state is the protocol declining to claim otherwise.
+
+    Collect, dismiss and a dialog reply answer `204` and no body at all, so they have no model here:
+    what they changed is visible in the next read, and inventing a body for them would be a second
+    place for the same fact to be wrong.
+    """
+
+    detail: str | None = None

taskwire/contrib/threads.py

@@ -0,0 +1,43 @@
+"""Carrying the ambient reporter across a thread boundary (TW-AMB-006).
+
+`contextvars` propagate along `await`, and they propagate into `asyncio.to_thread`. They do **not**
+propagate into `loop.run_in_executor`, which is the trap: the call looks like the same thing, the
+code inside it runs, and every `await progress.set(...)` in there is a silent no-op (TW-AMB-002). The
+symptom is a progress bar that stops moving for exactly the duration of one phase, with nothing
+logged anywhere and no exception to catch.
+
+```python
+# The trap. Nothing raises; the reporting inside `heavy` simply vanishes.
+await loop.run_in_executor(None, heavy)
+
+# Either of these carries the binding:
+await asyncio.to_thread(heavy)
+await loop.run_in_executor(None, copy_context_to(heavy))
+```
+"""
+
+from __future__ import annotations
+
+import contextvars
+import functools
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def copy_context_to(fn: Callable[..., T]) -> Callable[..., T]:
+    """Wrap `fn` so it runs in a copy of the caller's context.
+
+    Take the copy **now**, at wrap time, on the calling thread - that is the whole trick. Copying
+    inside the wrapper would copy the executor thread's context, which is the empty one this helper
+    exists to avoid.
+    """
+    context = contextvars.copy_context()
+
+    @functools.wraps(fn)
+    def run(*args: Any, **kwargs: Any) -> T:
+        return context.run(fn, *args, **kwargs)
+
+    return run

taskwire/contrib/viewsets.py

@@ -0,0 +1,292 @@
+"""The request/response half of the protocol, as a `fastapi-viewsets` ViewSet.
+
+Imports FastAPI and fastapi-viewsets; nothing in `taskwire/` outside `contrib` may (TW-CORE-006).
+
+## What an application does
+
+One call, and the whole REST surface exists::
+
+    from fastapi import APIRouter, FastAPI
+    from taskwire.contrib.viewsets import register_taskwire_rest
+
+    app = FastAPI()
+    router = APIRouter()
+    register_taskwire_rest(router)          # <- the entire REST transport
+    app.include_router(router)
+
+That call registers the context processor taskwire needs, applies `@route_viewset` and mounts six
+endpoints - **on REST and on muxws both**, since `route_viewset` publishes a viewset on the two
+transports at once. There is deliberately nothing else to wire: an application that has to remember a
+second call is an application where somebody eventually forgets it, and the failure would be a
+progress bar that never moves with nothing logged.
+
+## Why a viewset rather than a hand-rolled router
+
+Three things fall out of it that are awkward to build twice:
+
+- **`@action_configuration`** supplies the middle level of `raise_on_cancel`'s three-level
+  resolution (settings -> per-viewset/per-action -> per-call keyword). taskwire's core knows only
+  the outer two, because a mechanism resolving configuration from settings through a class to a
+  method is meaningless without viewsets - so this level exists only here.
+- **The middleware chain** - auth, session, rate limiting - applies to taskwire's endpoints the same
+  way it applies to the application's own, instead of taskwire inventing a second way to be
+  protected.
+- **One schema.** The FE proxy validates itself against `/schema`, so an endpoint that moved and a
+  client that did not find each other at startup rather than in production.
+
+## What is NOT here
+
+`taskwire.rest` holds every decision these endpoints make and imports no framework at all
+(TW-REST-001). This module builds a `Client`, calls a handler and translates `(status, payload)`.
+That split is why the same behaviour is testable with no server running, why `contrib/asgi.py` can
+serve the identical protocol with nothing installed but Python, and why the muxws transport can
+reach the same handlers over a stream instead of over HTTP.
+"""
+
+# NO `from __future__ import annotations` in this module, deliberately.
+#
+# `route_viewset` introspects these signatures with a plain `inspect.signature()` and hands the
+# return annotation on as the response model. Under the future import every annotation is a *string*,
+# so `-> None` arrives as the truthy `"None"` and FastAPI rejects it against a 204. The rule is
+# narrow but it has teeth: a module a third-party decorator reads signatures off must expose real
+# objects, not text. Everything else in `taskwire/` keeps the import.
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi_viewsets.conf import settings as viewset_settings
+from fastapi_viewsets.context import Context
+from fastapi_viewsets.decorators.route_viewset import route_viewset
+from fastapi_viewsets.response_classes import NOT_FOUND_RESPONSE
+
+from ..delivery import Client
+from ..headers import CONNECTION_HEADER, TOKEN_HEADER  # noqa: F401 - re-exported
+from ..rest import collect_result, dismiss_result, get_operations, get_snapshot, reply_to_dialog, request_cancel
+from ..settings import configured, settings
+from . import schema
+
+# The three keys the context processor contributes. Namespaced, because the context dict is shared
+# with every other processor the application has configured.
+SESSION_KEY = "taskwire_session"
+"""Where the namespace `session_resolver` returned sits in the context."""
+
+CONNECTION_KEY = "taskwire_connection"
+"""Where the value of `CONNECTION_HEADER`, or `None`, sits in the context."""
+
+TOKEN_KEY = "taskwire_token"
+"""Where the value of `TOKEN_HEADER`, or `None`, sits in the context.
+
+Read by `taskwire.contrib.celery`'s dispatch hook (TW-CELERY-007): a `celery_viewset_client` action
+has no `Request` of its own, only whatever a context processor put in `context` before dispatch, and
+this is the one key that carries the token across that boundary.
+"""
+
+
+async def taskwire_context_processor(request: Request, _viewset: Any = None) -> dict[str, Any]:
+    """Lift the namespace, the connection id and the token off the live request, once, per action.
+
+    A viewset endpoint never receives the `Request` - `route_viewset` reserves that parameter name
+    and strips it before FastAPI sees the signature - so this processor is the supported way in, and
+    it is the *only* place taskwire calls `session_resolver` on the REST path.
+
+    A `None` namespace is legal and means the application opted this caller out entirely
+    (TW-AMB-009). It does not mean "nobody is logged in": an anonymous visitor still has a session,
+    and conflating the two would hand every anonymous visitor the same register.
+    """
+    resolver = configured.session_resolver
+    return {
+        SESSION_KEY: resolver(request) if resolver is not None else None,
+        CONNECTION_KEY: request.headers.get(CONNECTION_HEADER),
+        TOKEN_KEY: request.headers.get(TOKEN_HEADER),
+    }
+
+
+async def _client(context: Context) -> Client:
+    """Build the `Client` every handler in `taskwire.rest` takes."""
+    return Client(
+        session=await context[SESSION_KEY],
+        connection=await context[CONNECTION_KEY],
+        request=None,
+    )
+
+
+def _unwrap(status: int, payload: dict[str, Any] | None) -> dict[str, Any]:
+    """Translate `(status, payload)` into a return value or an `HTTPException`, and nothing more.
+
+    Every status this raises on was decided in `taskwire.rest`; none is invented here. In particular
+    404 covers both "unknown token" and "somebody else's token" (TW-SEC-002) - a 403 would confirm
+    that a token exists in *some* namespace, which turns the endpoint into an oracle for enumerating
+    other people's operations.
+    """
+    if status >= 400:
+        raise HTTPException(status_code=status, detail=(payload or {}).get("detail", "error"))
+    return payload or {}
+
+
+def _check(status: int, payload: dict[str, Any] | None) -> None:
+    """`_unwrap` for the actions that answer `204` and no body.
+
+    Collect, dismiss and a dialog reply change something the *next read* reports; none of them has a
+    body of its own. Returning `None` here is what makes FastAPI send an empty 204 rather than the
+    `null` an untyped return would serialise to.
+    """
+    _unwrap(status, payload)
+
+
+class TaskwireViewSet:
+    """The six endpoints of TW-REST-004, keyed by token.
+
+    The token is the pk, which is not a convenience: it **is** the identity of an operation and
+    there is no other key anywhere in the system (TW-KEY-001). It is an address rather than an
+    authorization grant (TW-SEC-003) - holding one lets you watch an operation you could already
+    reach, and the namespace decided that before any of these methods ran.
+
+    ## Why this declares its own routes instead of inheriting the CRUD mixins
+
+    taskwire is not a collection of one type. `list` answers a `Register` - operations, the
+    aggregate, and the `poll_after_ms` that TW-REST-014 makes binding on the next poll - while
+    `retrieve` answers a `Snapshot`. `ImplMixin` is generic over a single `T`, so wearing it here
+    would mean stubbing five `container_*` methods that can never run, and the stubs would be the
+    only evidence that the shape was wrong.
+
+    What the viewset layer is actually wanted for arrives regardless: the middleware chain,
+    `@action_configuration`, one OpenAPI schema and the `/schema` endpoint the FE proxy validates
+    itself against.
+
+    There is no `create`: an operation is started by the application's own action, and the token is
+    the entire link between that command and taskwire's commentary on it (TW-CORE-007). Nor is there
+    `update` or `destroy` - progress is written by the operation and by nothing else (TW-PROG-012),
+    and an operation ends by finishing, failing or being cancelled, never by being deleted.
+    """
+
+    __router = APIRouter()
+
+    @__router.get("", summary="Every shared operation of this namespace, with its aggregate")
+    async def list_items(self, context: Context) -> schema.Register:
+        """`GET {prefix}` - the central endpoint, and the one an ordinary client polls.
+
+        Takes no parameters (TW-REG-003), so there is none that could name another namespace: the
+        register a caller sees is decided entirely by `session_resolver`.
+
+        Returns the whole `Register` rather than `list[OperationSummary]` because `poll_after_ms` is
+        binding on the client's next poll (TW-REST-014) and the aggregate is computed over the same
+        read. Splitting them would cost a second round trip to learn how long to wait before the
+        first one.
+        """
+        status, payload = await get_operations(await _client(context))
+        return schema.Register.model_validate(_unwrap(status, payload))
+
+    @__router.get("{token}", responses=NOT_FOUND_RESPONSE, summary="The complete current state of one operation")
+    async def retrieve(self, context: Context, token: str) -> schema.Snapshot:
+        """`GET {prefix}/{token}` - everything about one operation, in one document.
+
+        This is what makes reconnect a single GET (TW-CORE-005): there is no event log, no sequence
+        number and no replay endpoint anywhere in the system, and a client is entitled to current
+        state only.
+        """
+        status, payload = await get_snapshot(await _client(context), token)
+        return schema.Snapshot.model_validate(_unwrap(status, payload))
+
+    @__router.post("{token}/cancel", status_code=202, summary="Ask an operation to stop")
+    async def cancel(self, context: Context, token: str) -> schema.Accepted:
+        """`202`, deliberately - an acknowledgement, never a completion (TW-CANCEL-003).
+
+        The operation stops when its own code next looks, which may be never. taskwire does not
+        revoke tasks, signal threads or interrupt blocking code (TW-CANCEL-009), and a `200` here
+        would claim a power the library does not have.
+
+        An operation holding an uncollected result refuses with `409` (TW-CANCEL-010): its work is
+        over and there is nothing left to interrupt, so the affordance there is dismiss, not cancel.
+        """
+        status, payload = await request_cancel(await _client(context), token)
+        return schema.Accepted.model_validate(_unwrap(status, payload))
+
+    @__router.post(
+        "{token}/collect", status_code=204, response_model=None, summary="Take the parked result and release it"
+    )
+    async def collect(self, context: Context, token: str) -> None:
+        """The result is handed over exactly once (TW-RES-010): whoever gets `204` owns it.
+
+        A second caller gets `409`. That matters with several tabs open on one namespace - without a
+        single arbiter, two tabs would each believe they had collected the same export. The value
+        itself was already in the snapshot the caller read; this call releases it, which is why
+        there is no body to return.
+        """
+        _check(*await collect_result(await _client(context), token))
+
+    @__router.post(
+        "{token}/dismiss", status_code=204, response_model=None, summary="Discard the parked result without taking it"
+    )
+    async def dismiss(self, context: Context, token: str) -> None:
+        """The same act as collect under a different name (TW-REST-008), differing only in
+        idempotence: dismissing what is already gone is not an error, collecting it twice is."""
+        _check(*await dismiss_result(await _client(context), token))
+
+    @__router.post("{token}/dialogs/{did}", status_code=204, response_model=None, summary="Answer an open question")
+    async def dialog_reply(
+        self,
+        context: Context,
+        token: str,
+        did: str,
+        reply: schema.DialogReply,
+    ) -> None:
+        """`did` is *this asking*, never the `dialog_id` (TW-DLG-001, TW-DLG-002).
+
+        The store is the single arbiter and first answer wins (TW-STORE-003). A second tab answering
+        the same question gets `409`, and the client library treats that as a normal outcome of a
+        namespace-wide question rather than as a fault (TW-DLG-011) - the losing modal simply closes.
+        """
+        _check(*await reply_to_dialog(await _client(context), token, did, reply.model_dump()))
+
+
+_registered: set[int] = set()
+
+
+def register_taskwire_rest(
+    router: APIRouter,
+    base_path: str | None = None,
+    *,
+    register_muxws: bool | None = None,
+) -> type[TaskwireViewSet]:
+    """Mount the whole request/response surface on `router`. The only call an application makes.
+
+    ```python
+    router = APIRouter()
+    register_taskwire_rest(router)
+    app.include_router(router)
+    ```
+
+    **The same six endpoints answer over both transports.** `route_viewset` publishes them on REST
+    and - through `fastapi_viewsets.mux_ws` - on muxws, where `process_command` dispatches a stream
+    into the identical routes with the identical validation, middleware chain and response models.
+    A client speaking only WebSocket therefore reaches exactly the surface a client speaking only
+    HTTP does, and there is no second implementation to keep in step.
+
+    `register_muxws` decides whether the muxws half is published: `None` defers to fastapi-viewsets'
+    own `viewsets_register_muxws` (True unless the application says otherwise), and `False`
+    leaves a deployment with REST alone. It is the only knob, because the two transports differ in
+    nothing else.
+
+    The context processor is **transport-blind**. `process_command` supplies the WebSocket
+    handshake's own headers as the baseline for every command, so `session_resolver` reads the same
+    cookie or `Authorization` header on a stream that it reads on a request, and `CONNECTION_HEADER`
+    arrives the same way - stated on the stream when the client states it. Nothing here branches on
+    how the call arrived, and nothing may.
+
+    Idempotent per router: calling it twice mounts one copy, because `route_viewset` registers
+    routes as a side effect and a doubly-mounted viewset answers every request twice through two
+    middleware chains.
+    """
+    if id(router) in _registered:
+        return TaskwireViewSet
+    _registered.add(id(router))
+
+    if taskwire_context_processor not in viewset_settings.viewsets_context_processors:
+        viewset_settings.viewsets_context_processors.append(taskwire_context_processor)
+
+    return route_viewset(
+        router,
+        base_path if base_path is not None else settings.rest_prefix,
+        pk_field_name="token",
+        register_muxws=register_muxws,
+    )(TaskwireViewSet)

taskwire/decorators.py

@@ -0,0 +1,88 @@
+"""The three result decorators (§5.1).
+
+**They are sugar over `result_kind` and nothing else** (TW-API-005). Each wraps a task or an action
+and declares the kind its operation will produce, so the opening `queued` write already carries it -
+which is what makes the operation classifiable and scopable on its first push (TW-PROG-009).
+
+An application declares its own kind by passing `result_kind` directly. These add no mechanism the
+keyword does not already have, and taskwire never validates the string against a known set: the
+frontend maps `kind` to a component exactly as it maps `dialog_id`, so a new kind is a frontend
+change and not a protocol one.
+"""
+
+from __future__ import annotations
+
+import functools
+
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+RESULT_KIND_ATTRIBUTE = "__taskwire_result_kind__"
+"""Where a decorated callable carries its declaration.
+
+An attribute rather than a registry: a registry would be a second place the kind could disagree with
+the operation, and it would outlive the import that filled it.
+"""
+
+RESULT_PARAMS_ATTRIBUTE = "__taskwire_result_params__"
+
+
+def _declare(fn: F, kind: str, params: dict[str, Any] | None = None) -> F:
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        return fn(*args, **kwargs)
+
+    setattr(wrapper, RESULT_KIND_ATTRIBUTE, kind)
+    if params is not None:
+        setattr(wrapper, RESULT_PARAMS_ATTRIBUTE, params)
+    return wrapper  # type: ignore[return-value]
+
+
+def downloadable_result(fn: F) -> F:
+    """`result_kind="taskwire.download"` - a `ref` the user fetches.
+
+    taskwire stores the pointer and never the file (TW-RES-007): it does not create, serve, refresh,
+    proxy, validate or delete what is behind the href, and has no opinion about who may fetch it.
+    Set `result_ttl` no longer than your own artefact retention (TW-RET-003), or the entry outlives
+    the file and the download is dead by the time somebody clicks it.
+    """
+    return _declare(fn, "taskwire.download")
+
+
+def panel_result(kind: str) -> Callable[[F], F]:
+    """`result_kind=kind` - a `value` a component renders. The application names it.
+
+    `@panel_result("acme.import_report")`. The name is the application's, taskwire never checks it,
+    and the frontend maps it to a component exactly as it maps a `dialog_id`.
+    """
+
+    def decorate(fn: F) -> F:
+        return _declare(fn, kind)
+
+    return decorate
+
+
+def dialog_result(dialog_id: str) -> Callable[[F], F]:
+    """`result_kind="taskwire.dialog"` with `params.dialog_id` set - a component to open.
+
+    The way to say "this operation finishes by showing the user something", for an operation that
+    would otherwise have nothing to collect and would therefore be private (TW-PRIV-001).
+    """
+
+    def decorate(fn: F) -> F:
+        return _declare(fn, "taskwire.dialog", {"dialog_id": dialog_id})
+
+    return decorate
+
+
+def declared_result_kind(fn: Any) -> str | None:
+    """The kind a decorated callable declared, or `None`. Used when the operation is opened."""
+    return getattr(fn, RESULT_KIND_ATTRIBUTE, None)
+
+
+def declared_result_params(fn: Any) -> dict[str, Any] | None:
+    """The params a decorated callable declared, or `None`. `dialog_result` is the only decorator
+    that sets them."""
+    return getattr(fn, RESULT_PARAMS_ATTRIBUTE, None)