70 lines
3.4 KiB
Markdown
70 lines
3.4 KiB
Markdown
# 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.
|