# ADR: an explicit boundary between input, intent and action

Status: accepted for developer API v1. September 30, 2026.

The immersive website demonstrates a future interface. It is not a sensor. The founder reports production voice-to-action, beta motion-to-action and active university smell R&D; the external acquisition deployments still require current integration evidence.

## Decision

The shared `sense-domain` Rust crate validates caller-supplied transcripts or normalized gesture identifiers and resolves declarative rules into typed action intents. It has no network, browser, database or shell dependency. Axum and Cloudflare Workers are HTTP adapters around that same policy. The Worker exports OpenAPI from its actual handler and schema definitions; the documentation build consumes this export together with the same capability, action and template catalogs.

The Rust CLI is a transport client. TypeScript and Python SDKs expose a transport port and an explicit handler registry. Reading an intent does not execute it. The application registers handlers, controls permissions and decides when to dispatch. This separation supports custom navigation, text, media, scenes and workflow integrations without giving the public API an arbitrary execution primitive.

## Ports and responsibilities

| Boundary | Responsibility |
| --- | --- |
| Acquisition adapter | Obtain explicit user consent; turn audio or movement into a supplied transcript or gesture. Separate provider configuration and evidence are required. |
| Domain resolver | Validate bounded requests; normalize exact matches; apply enabled and confidence rules; emit intents deterministically. |
| HTTP adapters | JSON, CORS, request limits, rate limiting, errors and generated OpenAPI. |
| SDK transport | Base URL, timeout, cancellation, typed errors; no implicit action retries. |
| Application handler | Execute a known action under application permissions; implement confirmation and idempotency where appropriate. |
| Documentation adapter | Generate endpoint/schema/catalog reference and per-sense artifacts from code; supplement it with reviewed narrative and proposed roadmap. |

## Alternatives and tradeoffs

Direct server-side execution of submitted shell commands or webhook URLs would introduce remote execution and SSRF risks with no authenticated ownership model. It is excluded. A separate hand-written OpenAPI file would drift from two transports; code-derived types and adapter contract tests replace it. Introducing a sensor or transcription provider without verified configuration would misrepresent acquisition; adapters remain explicit and independently testable.

The stateless public resolver intentionally stores no submitted input. Operational infrastructure may still retain request metadata. No health-information service, medical inference, SOC 2 report, ISO certification or HIPAA-ready deployment is implied. Contact capture uses its separate existing consent and persistence boundaries.

## Contract and evolution

The API prefix is `/api/v1`. Clients must use the published schema and handle structured errors and unavailable senses. Changes to action types, matching semantics or payload validation require domain, adapter and SDK contract tests. Breaking changes require a new major API or SDK version. Confidence is supplied by the acquisition adapter, not measured or inferred by this resolver. Rule order determines intent order; application handlers own deduplication and safeguards for irreversible actions.

## Reproduction and evidence

Run the Docker Compose stack for the Axum adapter and static docs. Run the Worker host tests and WASM lint for deployment compatibility. The developer release workflow packages checked binaries and SDK archives, records the exact source SHA and SHA-256 checksums, retains GitHub artifacts and publishes the same archives through the website. The first release and custom documentation domain each require their own verification; configuration alone is not publication evidence.

Official sources and version checks are recorded in developer-api-evidence.md, developer-release-evidence.md, the CLI/SDK documentation and evidence.md. Proposed compliance work and sources are maintained in `developer/roadmap.json`.