Files
notarius/docs/adr/0021-compose-native-kits-and-prompt-declared-resources.md

4.3 KiB

ADR-0021: Compose native kits and prompt-declared resources

Status: Accepted Date: 2026-11-22

Context

Notarius duplicated configuration assembly, resource registration, completion types, inspection, CLI parsing, and provider scheduling that the adopted kits now supply. Keeping those wrappers would preserve competing ownership rather than protect the application's typed artifact boundary.

Decision

Use ConfigKit, PromptKit, CommandKit, ckconfig, and ckprompt directly at their respective application boundaries. The composition root owns one application load per selected configuration and constructs one shared native engine for all selected model roles from that original result. Runtime and whole-app or focused inspection share captured sources and native provenance, not a settings reserialization or a second loader. ConfigKit retains ownership of composition mechanics under ADR-0020. Version 6 replaces version 5 without a compatibility parser.

Assemble bundled provider resources, embedded application resources, and optional operator companions beside the selected main source through native contexts and precedence. Native declarations own qualified resources, inheritance, default output contracts, and schema selections. PromptKit prepares schemas and owns structural validation and repair. Application modules retain prompt meaning, interpretation, and static resource-ID dependencies, not manifests, response-schema registries, asset fingerprints, virtual mounts, or fallback-profile registration. The root assets package remains an ordinary content-only embedded leaf.

Model-executing code uses native requests, results, exchanges, errors, and observations. Pure domain models, codecs, source resolution, and deterministic helpers remain independent. CommandKit and its integrations own standard command declarations, parsing, inspection, and presentation; Notarius supplies loaders, pipeline commands, request inputs, and report content. Shared loaders and offline preflight do not allocate run storage or perform implicit provider probes.

One ready-job worker pool bounds extraction and merge/normalize continuations together. Prerequisite waits occupy no worker; nested validation and correction stay inside the current job. Native engine/backend admission is independent. Inject no backend concurrency/queue defaults, cross-backend ceiling, extra queue, or application capacity retries. Preserve stable scope ordering and cancellation draining. A completed turn releases admission before nested assessment.

This supersedes ADR-0019's old source adapter and private-type boundary; its fingerprint policy is replaced by ADR-0023. It replaces the asset registration portions of ADR-0004 and ADR-0011, retaining domain-first packaging, semantic ownership, and the content-only leaf. It replaces ADR-0018's version 5 selection, not ConfigKit adoption or ADR-0020's ownership. ADR-0010's workload-oriented profile intent remains; native qualified resources replace its older source form.

Alternatives considered

  • Keep private completion, loader, and inspection adapters. This duplicates kit behavior and obscures the actual execution contract.
  • Adopt only PromptKit and defer CommandKit. Temporary command/report wrappers would need another cutover and could select different configuration.
  • Retain a global LLM scheduler above native admission. This adds a second queue and couples independent backends without a selected product requirement.

Consequences

The kits are deliberate dependencies at execution and composition boundaries; typed application assessment and durable domain artifacts remain distinct. Upstream changes require review of the public APIs actually consumed, rather than preservation of old wrappers. Workers do not promise a global provider-call ceiling or backend saturation. CLI and configuration compatibility is intentionally broken; artifact schemas are not redesigned. Exact public syntax and dependency integration details belong in the canonical configuration, CLI, and integration references, not copied library manuals here.