notarius/docs/adr/0011-centralize-llm-assets.md

ADR-0011: Centralize LLM-facing assets in a content-only package

Status: Accepted Date: 2026-08-05

Context

LLM prompts, private response schemas, generic schemas, and fallback profiles are authored and reviewed as content, but package-local embedding scattered that content across implementation trees. Finding all of the assets that contribute to a prompt family required navigating code ownership boundaries rather than a single discoverable content boundary.

The repository must retain module ownership of prompt semantics, schema identities, registration, and prompt-cache behavior. Durable artifact schemas and non-LLM domain data have different compatibility and ownership rules, so they must not move merely because they are embedded files.

Decision

LLM-facing content is embedded by the root assets package. It is a data-only dependency leaf: its single FS() fs.FS API returns the read-only embedded filesystem, and the package contains no business logic or internal or PromptKit dependencies. The accepted import path is gitea.maximumdirect.net/eric/notarius/assets; it makes repository-owned content available to its consumers, not a public extension contract.

Consumers scope that filesystem to the subtree they own before reading or registering content. Modules continue to own their manifests, prompt ordering, private response-schema identity, and registration. Centralizing physical files does not centralize domain semantics or transfer those responsibilities to the root package.

The root package contains prompt content, private LLM response schemas, generic LLM schemas, shared fragments, and fallback profiles. Durable artifact schemas and non-LLM domain data remain with their current owners. A module fingerprint is derived from its manifest-selected module and shared files, rather than from an entire asset tree. The relocation is accepted to cause a one-time checkpoint invalidation.

This decision supersedes only the physical asset-co-location portion of ADR-0004's decision that places domain-specific prompt fragments and schemas within the domain tree. ADR-0004's domain-first packaging and registrar ownership decisions remain accepted.

Alternatives Considered

• Keep package-local assets. This preserves physical co-location with code but makes prompt-author discovery and cross-family review unnecessarily costly.
• Use internal/llmassets. This would hide content from legitimate owners outside the internal subtree and would make the root asset boundary depend on implementation-layer placement.
• Build a behavioral central registry. This would mix content discovery with prompt selection and registration behavior, moving module semantics into a shared registry.
• Use runtime filesystem overlays. This would add runtime configuration and failure modes where compile-time embedded content is sufficient.

Consequences

Prompt authors can find in-scope LLM content in one top-level tree while module packages continue to define its meaning and registration. Consumers have an explicit, narrow dependency on only the content they need. The root package is intentionally importable but must remain a stable, content-only leaf rather than becoming a general extension API.

The initial relocation invalidates existing checkpoints once. Later checkpoint identity changes remain limited to the manifest-selected prompt and shared content, so unrelated files do not trigger recomputation.