# 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 voice-to-action as fully implemented and motion-to-action in development. The founder reports smell R&D underway with several universities; institutions and agreements are not disclosed or independently verified. 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 an independent transport client and product: it has its own Cargo workspace, lockfile, manual and documentation page, and it shares no code with any SDK. The TypeScript, Python, Go and Rust SDKs each 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         | Explicit base URL, bounded HTTP waiting, cancellation and typed errors; no SDK retry loop. Injected transports own their lower-level policies.                                       |
| 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; render the prompt-first developer pages; supplement them 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.

## Documentation experience

Decision, October 1, 2026: the developer site presents a prompt-first experience with a detailed reference. It is split into Live, CLI, SDK, Downloads and Reference pages under `/developers/`. Installing, updating and wiring are prompts the visitor hands to a coding agent; no page asks a person to type a command. Prompts read the published download manifest, verify SHA-256 before running anything, and end by showing a live 200. Every 200 on the Live, CLI and SDK pages is a real same-origin API call: a pulse travels to the API, the HTTP status rolls into place and the actual JSON payload unfolds. Reduced motion shows the same final state without animation. Commands, flags, method signatures and the error catalogue remain available, collapsed under "Under the hood" and on the Reference page, because agents still need them.

`developer/experience.js` holds the prompt and language catalog at build time; `scripts/developer-docs.js` renders pages; `developer/signal.js` (live stage), `developer/downloads.js` (manifest interpretation) and `developer/docs.js` (page wiring) run in the browser. Prompts contain live slots for the serving origin and the chosen language.

October 15 navigation refinement: `developer/navigation.js` keeps language/return URL policy separate from page rendering and applies the embedded navigation catalog through a DOM adapter. All five destinations, including Reference, share one navigation group; the mobile group wraps to keep every destination visible. Every page has a prominent same-tab experience return to `/site/?lang=en|fr`, and internal navigation carries that language forward. Only the navigation and existing bilingual entrance are localized; authored API prose and external client contracts are unchanged.

Four SDKs are maintained and have source tests and packaging gates here: TypeScript, Python, Go (standard library) and Rust (rustls, optional reqwest adapter). The public manifest determines which versions and languages can actually be downloaded. For any other language, the SDK page offers a prompt that has the visitor's agent generate a client from the published OpenAPI and reference. The page and the prompt label such code as generated, not an Ursly package. Ursly does not test those clients.

## Developer integration and copied programs

Decision, October 19, 2026: retain the prompt-first pages and make the complete integration contract directly available to developers and coding agents. [`developer-sdk-guide.md`](developer-sdk-guide.md) records setup, the four-language operation matrix, matching and byte limits, every action payload, handler registration and ordering, errors, timeouts, cancellation, retries and acquisition boundaries. The build copies that reviewed narrative to `developers/artifacts/sdk-guide.md`; the SDK, Downloads, Reference, `llms.txt` and agent reference link it. Generated OpenAPI and catalogs remain the authority for API schemas and available actions; the guide explains how to use them.

`developer/composer.js::sdkSnippet` is the single source for copied SDK programs in both the intent composer and the SDK page. Programs contain their imports and entry points, register print-only handlers, resolve one request and dispatch that same validated resolution. Python loads the JSON request explicitly, preserving JSON null and boolean values. Rust translates whole JSON string escape tokens and preserves finite confidence values without decimal rounding. No example depends on an undeclared router, editor or application function.

`scripts/generate-sdk-examples.js` exports those exact programs and an expected-result manifest after reading catalogs from an explicitly supplied test API. The package-consumer verification compiles and executes exported programs against installed SDK archives, checks the single outbound resolution request with schema-scoped payload equality, the API's resolution status and ordered intent IDs, and the returned dispatch-result count. Callback invocation count and order are tested separately in the SDK suites. The cases span supplied voice and motion, every catalogued action, raw templates, disabled rules, confidence options, escaped Unicode and multi-action workflow parameters. These checks exercise the documented integration path; they do not validate microphone, camera or other acquisition hardware.

Release status is derived from a validated manifest and the requested language's actual archive kind. Current-source examples use the Ursly names introduced for distribution 0.2.0. Listed 0.1.x archives remain downloadable with an explicit earlier-package label and their own manual; an absent Go or Rust kind remains unpublished. A live website revision, a source package version and an immutable archive version are separate facts.

Dispatch validates all intents and preflights every required handler before executing any callback. Once execution begins, callbacks run in intent order and stop at the first handler failure without rollback or automatic replay. HTTP deadlines bound transport waiting, not handler duration. Cancellation is cooperative around handler boundaries; language-specific transport behavior is documented in each SDK manual. The SDKs schedule no retry loop, but injected transports and standard HTTP libraries can have their own policies (for example, Go may retry an idempotent GET on a reused connection).

## 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.

October 15 product-stage correction: the code-derived capability catalog describes Motion as `development`, following the owner's latest status. `apiAvailable: true` and `acquisition: client_gesture` continue to describe only supplied-identifier intent resolution. TypeScript, Python, Go and Rust source validators/types add `development` and retain `beta` for earlier responses; invalid values are still rejected. The October 19 audit downloaded and hash-checked the immutable 0.1.0 TypeScript and Python archives, then successfully read capabilities, actions and templates against both production and the local audit API. Those measured catalog checks supersede the earlier speculative concern that the archives might reject `development`; they do not prove every current feature works with an older client. Distribution and compatibility of a separately versioned new client release require their own checks. The metadata update neither changes acquisition capability nor hand-maintains an OpenAPI artifact.

## 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`.

## Documentation origin and public name

Ursly is the public brand; existing CLI/SDK import names remain stable. `DOCS_HOST` configures the separate developer origin. A pure path policy in `cloudflare-worker/src/docs_routing.rs` maps only GET/HEAD requests on that exact hostname to bundled documentation; API, experience, downloads and main-host paths retain their existing adapters. The generated agent references consume the same exported schema/catalogs as the HTML documentation. The animated entrance is progressive enhancement: direct anchors, machine references and readable documentation require no animation or identity check. Deployment verification compares the generated document at root and all relative asset aliases byte for byte.
