82 lines
4.7 KiB
Markdown
82 lines
4.7 KiB
Markdown
|
# Audita request: main-relative companion resources
|
||
|
|
|
||
|
|
Consumer requirements against ConfigKit v1.1.0. These complement the proposed
|
||
|
|
[main-relative underlays and overlays](main-relative-inputs.md); that roadmap
|
||
|
|
owns upstream API design and implementation planning.
|
||
|
|
|
||
|
|
## What Audita is doing
|
||
|
|
|
||
|
|
Audita is a transcript-processing CLI adopting ConfigKit, PromptKit, and
|
||
|
|
CommandKit's native loading and inspection workflows. ConfigKit should own
|
||
|
|
discovery, imports, composition, overlays, and configuration resolution. Audita
|
||
|
|
should receive the resolved configuration and then apply transcript-specific
|
||
|
|
business logic.
|
||
|
|
|
||
|
|
The main application configuration is either an explicit file or the result of
|
||
|
|
native `SearchConfig` discovery. Companion resources should follow the directory
|
||
|
|
containing the selected main file, regardless of the process working directory:
|
||
|
|
|
||
|
|
| Resource | Intended location and use |
|
||
|
|
| --- | --- |
|
||
|
|
| Glossaries | Optional `glossary.yml` and recursive `glossary/` imports, mounted at `glossary_collections` in an application underlay. |
|
||
|
|
| PromptKit definitions | Optional `prompts.yml` and recursive `prompts/` imports, in an operator tier above embedded Audita prompts and PromptKit's bundled catalog. |
|
||
|
|
| Selected named overlay | Beside the main file, using native `overlays/<name>.yml` lookup. |
|
||
|
|
|
||
|
|
Both recursive imports select `*.yml` and `*.yaml`. Audita supplies their import
|
||
|
|
declarations, so operators need not repeat discovery boilerplate in every main
|
||
|
|
file or create a manifest just to use a resource directory. Each pair composes
|
||
|
|
as peers within its tier; native precedence and diagnostics remain authoritative.
|
||
|
|
Embedded assets retain their separate filesystem contexts.
|
||
|
|
|
||
|
|
For example, selecting `/srv/campaign/audita.yml` while running from `/tmp`
|
||
|
|
should use `/srv/campaign/glossary/`, `/srv/campaign/prompts/`, and
|
||
|
|
`/srv/campaign/overlays/<name>.yml`.
|
||
|
|
|
||
|
|
An aggregate `overlays.yml` was also suggested for symmetry. It is not supported
|
||
|
|
by today's named-overlay contract and is a separate possible enhancement, not
|
||
|
|
necessary to solve the directory-binding requirement described here.
|
||
|
|
|
||
|
|
## Missing API support
|
||
|
|
|
||
|
|
In the current [layered API](../config.md#layered-loading), `SearchConfig`
|
||
|
|
selects the main during loading, while underlay filesystem contexts and
|
||
|
|
`OverlayFilesystem` must be supplied beforehand. Audita cannot bind these to
|
||
|
|
the selected directory without duplicating discovery or performing a preliminary
|
||
|
|
load. Imports in the main file would be peers, not the required lower-priority
|
||
|
|
underlay.
|
||
|
|
|
||
|
|
1. **Bind an underlay import context to the selected main directory.** Audita
|
||
|
|
needs this for an application-supplied mapping or bytes containing native
|
||
|
|
import declarations, including optional file and recursive-directory imports
|
||
|
|
and their destinations. A constructor for a required main-relative file alone
|
||
|
|
would not cover this workflow. Resolve the relationship within one layered
|
||
|
|
load, then let existing import machinery acquire and compose the resources.
|
||
|
|
2. **Derive the selected overlay context during that same load.** Support an
|
||
|
|
explicit request for main-relative lookup with either an explicit or discovered
|
||
|
|
main file. Preserve native overlay naming, precedence, and errors. Audita's
|
||
|
|
intended lookup base is the main file's directory; distinguish that choice
|
||
|
|
from a potentially broader filesystem containment root.
|
||
|
|
3. **Make absent-main behavior explicit.** Audita permits optional discovery to
|
||
|
|
find no main file and still run with sufficient defaults and CLI settings.
|
||
|
|
The API should allow an explicit policy for dependent resources in that case,
|
||
|
|
without manufacturing a main source or guessing from unsuccessful candidates.
|
||
|
|
A caller-supplied fallback directory is one useful option; whether Audita
|
||
|
|
chooses the working directory or skips automatic companion imports remains
|
||
|
|
an application decision. Failures reading a selected main must remain terminal.
|
||
|
|
|
||
|
|
PromptKit's separate engine can be constructed after application loading and use
|
||
|
|
the selected main's recorded source context. Existing context inspection may
|
||
|
|
already suffice there; this request does not require combining the two schemas
|
||
|
|
or adding a second discovery API.
|
||
|
|
|
||
|
|
## Completion from Audita's perspective
|
||
|
|
|
||
|
|
One native application load can discover the main, bind its companion imports
|
||
|
|
and selected overlay, and return normal source evidence and errors. Changing
|
||
|
|
only the invocation directory does not relocate companions of the same selected
|
||
|
|
main. Processing and inspection share this behavior, with no Audita directory
|
||
|
|
walker, configuration parser, discovery pass, or preliminary full load.
|
||
|
|
|
||
|
|
The API shape is ConfigKit's choice. The important addition is native context
|
||
|
|
binding for both declared underlay imports and selected overlays.
|