# ADR 0081: Generic native operations use managed definitions

> Source: https://github.com/max-listov/stitchkit/blob/master/docs/decisions/0081-generic-native-operations-use-managed-definitions.md

---

# ADR 0081 — Generic native operations use managed definitions

## Context

ADR 0019 put generic wait, guarded-download and upload mechanics in Stitchkit,
but exposed them only as direct MCP SDK registrars. A consumer using those
helpers therefore had to place them under `rawTools`, deliberately bypassing
the lifecycle, application context, hooks, cancellation and unified surface
introspection that ADRs 0055 and 0057 established for managed pathless tools.

Copying those operations into application-owned `defineRuntimeTool` handlers
would recover policy at the cost of duplicating framework mechanics.

## Decision

- `defineWaitTool`, `defineDownloadTool` and `defineUploadTool` return ordinary
  `RuntimeToolDefinition` data. They use the canonical runner and can be mounted
  on MCP, Agent or an explicit subset of those transports.
- Each factory takes Zod input/output schemas, stable operation identity and
  typed callbacks. Success is neutral validated data; failures enter the
  canonical `AppError -> ToolResult` path.
- Wait polling/sleep, guarded fetch/write and upload invocation each have one
  transport-neutral operation implementation. Active-call cancellation reaches
  the wait and download boundaries; upload callbacks receive the typed context
  and its signal.
- `mountWait`, `mountDownload` and `mountUpload` remain deliberate low-level MCP
  adapters over the same operations. They preserve their text/`isError` wire
  contract and make no lifecycle or hook guarantees.
- `mountViewFile` remains a separate raw media boundary. This decision does not
  invent a second runtime-tool runner or a compatibility alias.

## Consequences

- Generic imperative tools participate in the same lifecycle/RBAC, hooks,
  request context, schema preparation, collision checks and introspection as
  every other managed runtime tool.
- MCP and Agent execute one definition, so identity and behavior cannot drift
  between transports.
- Existing raw-mount users are not silently migrated to managed semantics; they
  opt into the factories by placing their definitions in `runtimeTools`.
- Framework mechanics remain domain-free: consumers still provide poll/done,
  URL resolution and upload behavior.