base-layer/configkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

Plan main-relative companion inputs

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-09 18:39:25 +00:00
parent c51bea9b4f
commit ae0c94d3c6
3 changed files with 322 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
docs/roadmap/audita-request.md Normal file
View File

@@ -0,0 +1,81 @@
# 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.