From 64786140e8911ae85b34f8eb766ad4a2972179ff Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 8 Nov 2026 18:51:37 +0000 Subject: [PATCH] Plan ConfigKit glossary composition and derived runtime views --- docs/roadmap/configkit.md | 9 +- docs/roadmap/glossary-stages.md | 421 +++++++++++++++++++------------ docs/roadmap/library-adoption.md | 16 +- 3 files changed, 276 insertions(+), 170 deletions(-) diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 89e188b..d8f25f1 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -126,10 +126,13 @@ file remain terminal. together with its [CLI precedence and native-support boundary](glossary-stages.md#cli-overrides-and-stage-precedence--resolved). Use its [separate glossary and protection selections](glossary-stages.md#glossary-selection-and-protected-vocabulary--resolved), including root protection defaulting through recorded application resolution. - Apply its [post-handoff application-resource path policy](glossary-stages.md#relative-paths-and-source-context--resolved) - while leaving upstream configuration resolution to ConfigKit. + Adopt its [glossary configuration ownership boundary](glossary-stages.md#glossary-configuration-ownership--resolved): + glossary assets use native loading, composition, inheritance, collection + identity, and typed decoding before handoff. Audita derives consumer-specific + runtime views from that result and removes its separate glossary YAML loader. Complete its required durable decision record. The glossary roadmap owns - the remaining list-input, combined-entry, and attribution decisions. This + the remaining collection schema, composition scope, identity, runtime-view, + selection-input, and attribution decisions. This application scope model does not change native source composition or sibling-inheritance semantics. diff --git a/docs/roadmap/glossary-stages.md b/docs/roadmap/glossary-stages.md index 8177706..7eacddd 100644 --- a/docs/roadmap/glossary-stages.md +++ b/docs/roadmap/glossary-stages.md @@ -2,73 +2,106 @@ **Updated:** 2026-11-08 -**Status:** Accepted scope and configuration model for the next Audita major -release. Remaining design decisions and implementation are pending. The +**Status:** Accepted feature scope, ownership, and stage-selection semantics for +the next Audita major release. Collection schema, remaining design decisions, +and implementation are pending. The [master roadmap](library-adoption.md) owns sequencing and release completion. ## Baseline and Target The current [CLI](../cli.md) accepts one glossary input for a processing run. The [pipeline configuration](../config.md) supports repeated glossary stages, -but does not select a different glossary input for each occurrence. +but does not select different glossary inputs for each occurrence. Glossary +files currently have a separate [YAML input contract](../integrations/transcript-glossary-files.md#glossary-yaml-contract). -Allow operators to run ordered glossary stages against different glossary inputs -within one processing run. For a D&D transcript, the first glossary stage can -use `party.yml` and the second can use `spells.yml`. Each stage uses its selected -glossaries and processes the transcript resulting from earlier stages. Operators -need not combine those inputs into one glossary or run Audita separately for -each pass. +Make glossaries and glossary collections reusable, composable configuration +assets loaded and composed by ConfigKit. Allow ordered stages to select different resolved +vocabulary within one processing run: for example, a focused party pass, a +focused spell pass, and grammar cleanup using both. Each stage processes the +transcript resulting from earlier stages. Operators need not maintain one +manually combined glossary or run Audita separately for each pass. -The major-release policy permits a hard cutover; the current single-glossary CLI -and pipeline representation do not constrain the target design. -The final representation belongs to the agreed -[version-3 application schema](configkit.md#application-schema-version--resolved), -with one hard cutover covering library adoption and this feature. +The major-release policy permits a hard cutover. The current single-glossary +CLI, standalone parser, and file schema do not constrain the target design. +Finalize the glossary representation with the agreed +[version-3 application schema](configkit.md#application-schema-version--resolved) +so operators migrate once. Exact collection, entry, and selection syntax remains +open below; the ownership and domain semantics in this roadmap are selected. + +## Glossary Configuration Ownership — Resolved + +Glossaries are configuration. ConfigKit owns their source loading, parsing, +composition, inheritance, collection operations, strict typed decoding, and +configuration provenance. Audita supplies the Go schema, collection identity +registrations where applicable, and domain validation through supported public +APIs. Use native imports and layering rather than an Audita YAML loader or +private glossary merge engine. + +Before transcript processing, hand off fully resolved, typed Go glossary +configuration and stage selections to Audita. Configuration-level domain checks +belong in the supported ConfigKit validation lifecycle; structural decoding alone +does not establish domain correctness. Audita's processing code must not reopen +glossary documents or parse arbitrary YAML after this handoff. Remove the separate +glossary decoding/composition path when the new contract lands. + +All configuration-source path and resolution behavior remains upstream-owned, +including glossary documents, imports, overlays, and source resource contexts. +Retain native source attribution through application resolution. A glossary +filename is a configuration source, not an application-data file for a second +post-handoff loader. Choose the source arrangement through ConfigKit's public +composition APIs; a string in an application field does not automatically cause +ConfigKit to load another document. The exact collection layout and load scope +must be settled before implementation. + +### Derived Runtime Representations — Resolved + +Keep the resolved configuration intact. Audita derives separate runtime views +for its consumers, preserving traceability to configured entries and selections: + +| Consumer | Derived representation | +| --- | --- | +| Glossary module LLM | Rich entries with terms, categories, descriptive comments/context when present, and other relevant configured fields. | +| Protected-term validator | Deduplicated recognized vocabulary prepared for deterministic matching. | +| Glossary-stage protection | Selected protected vocabulary minus the active glossary vocabulary. | +| Diagnostics and inspection | Resolved definitions and selections with their configuration origins, distinguished from derived runtime views. | + +ConfigKit's identity and composition rules govern which configuration records +coexist or replace one another. Runtime vocabulary deduplication governs whether +multiple valid records contribute the same recognized spelling. Do not use the +latter to suppress configuration conflicts or rewrite the resolved definitions. +Rich prompt data need not lose distinct definitions merely because their text +matches in the protection view. Audita owns matching, transcript-specific +validation, and the selected stage-specific transformations. Detailed handling +of ambiguous identities and rich-entry payloads remains open below. ## Root Defaults and Stage Overrides — Resolved -Define global stage settings at the configuration root. Represent the pipeline +Define global stage defaults at the configuration root. Represent the pipeline as an ordered `pipeline.stages` list of objects, each selecting a `module` and -optionally overriding stage settings. Use typed configuration fields, not a -separate variable-substitution language. The selected glossary configuration is: - -```yaml -version: 3 -glossaries: - - party.yml - - spells.yml -pipeline: - stages: - - module: glossary - glossaries: - - party.yml - - module: glossary - glossaries: - - spells.yml - - module: grammar -``` - -Resolve every stage independently against the global settings. Omitted stage -settings inherit their global values; explicit stage values override them. +optionally overriding stage settings. Resolve every stage independently against +the root settings. Omitted stage settings inherit; explicit stage values override. Preserve meaningful false, zero, and empty values under each setting's validation rules rather than treating them as omission. A stage override does not alter -the root settings or the defaults seen by later stages. +root settings or defaults seen by later stages. -In this example, the first glossary stage uses `party.yml` as its correction -input, the second uses `spells.yml`, and grammar inherits both glossary inputs. -All three stages inherit a protection selection containing both files through -the root default described below. Glossary stages then exempt their active -vocabulary from protection. Transcript changes carry forward between stages; -configuration overrides do not. Each consumer receives the appropriate selection from the -stage's effective settings, keeping correction/context inputs and protection -inputs distinct. +The names `glossaries` and `protected_terms` below identify the agreed correction/ +context and protection selection roles. Their final representation must select +resolved glossary configuration; direct file-path lists are not a settled schema +for this redesign. Collection definitions, collection references, and their field +names are part of the native configuration-shape decision below. Do not introduce +a general variable-substitution language. -Apply this model to settings governing stage processing. Invocation-wide -concerns such as configuration discovery, output destinations, and reporting -mode remain global. The selected scope inventory follows below. -Preserve stage order, repeated modules, and explicit empty-pipeline behavior. -Use native ConfigKit loading, presence, and provenance facilities; Audita owns -the meaning of stage scope and passes the effective settings to its consumers. +For the party/spells use case, the root selects both collections, the first +stage selects party vocabulary, the second selects spell vocabulary, and grammar +inherits both. All stages inherit the root protection selection by default; +glossary stages exempt their active vocabulary as described below. Transcript +changes carry forward; configuration overrides do not. Each consumer receives +the appropriate view of its stage's effective settings. + +Invocation-wide concerns such as configuration discovery, output destinations, +and reporting mode remain global. Preserve stage order, repeated modules, and +explicit empty-pipeline behavior. Use native ConfigKit presence and provenance; +Audita owns the domain meaning of stage scope. ## Configuration Scope — Resolved @@ -76,13 +109,14 @@ Settings governing an individual stage's requests, acceptance, or model-operatio budget support root defaults and stage overrides. Settings governing preprocessing, the invocation's shared resources, or its final outputs remain global. Classify by the setting's meaning and consumer lifecycle, not by where current code stores -it. The names below identify current settings; version-3 field representation -must preserve these scope decisions. +it. The inventory below records the selected scopes; version-3 field +representation must preserve these decisions. | Setting | Scope and rationale | | --- | --- | -| `glossaries` | Stage: ordered glossary files supplying correction and context vocabulary. | -| `protected_terms` | Stage: independently selected glossary files supplying protected vocabulary; defaults from root `glossaries` before stage inheritance. | +| `glossaries` selection | Stage: resolved glossary collections supplying correction and context vocabulary. | +| `protected_terms` selection | Stage: independently selected glossary collections supplying protected vocabulary; defaults from root `glossaries` before stage inheritance. | +| Glossary definitions and collection composition | Global: typed definitions composed through ConfigKit; runtime views are derived per consumer. | | Applicable confidence threshold | Stage: acceptance of that stage's proposals. | | Proposal and validation profile selection | Stage: models and generation settings appropriate to each role. | | `context.description` | Stage: prompt context shared by proposals and validators. | @@ -108,36 +142,37 @@ per-stage rechunking would be a separate feature decision. ### Glossary Selection and Protected Vocabulary — Resolved -Use `glossaries` at the root and on stages for an ordered sequence of glossary -file paths, including when only one file is selected. Combine the entries from -the selected files in declared order for the stage's glossary input. A glossary -module stage without an override receives the combined root selection; an -explicit stage list selects the files for a focused pass. Paths are direct file -selections, with no named catalog or variable-reference language. +Select correction/context vocabulary and protection vocabulary independently +at root and stage scopes. A glossary stage without an override uses the entire +root glossary selection; an explicit stage selection supports a focused pass. +An explicit protection selection is complete, not an additive set of extra +vocabulary. Do not implicitly union it with correction inputs or collections +selected by other stages. -Use `protected_terms` at both scopes for a separate ordered sequence of glossary -file paths, not literal term strings. Its entries supply the protected vocabulary. -Each list specifies the complete selection and replaces the inherited list; -`protected_terms` is not an additive list of extra glossaries. Do not implicitly -union it with correction inputs or with files selected by other stages. +These domain rules survive the configuration redesign. The native collection +shape, entry order, and exact selection representation are open; configuration +composition must follow ConfigKit's own contracts rather than a blanket local +rule to concatenate independently parsed files. Resolve these settings in this order: -1. Load configuration and apply explicit CLI assignments through ConfigKit. +1. Load and compose glossary configuration and apply explicit CLI assignments + through ConfigKit. 2. If root `protected_terms` is omitted, derive it from a copy of the effective root `glossaries`. Preserve any explicit root protection selection, including `[]`. 3. Independently inherit the effective root `glossaries` and `protected_terms` into each stage wherever that stage omits the corresponding setting. A stage override replaces only its own selected list. -4. For a glossary module stage, construct its effective protected vocabulary by - subtracting its active glossary terms from its selected protected terms. +4. After the configuration handoff, derive runtime views. For a glossary module + stage, construct its effective protected vocabulary by subtracting its active + glossary terms from its selected protected terms. Non-glossary stages use their selected protection vocabulary without this subtraction. Protection therefore defaults at the root before stage inheritance. It does not -fall back to a focused stage's glossary list. In the example above, no operator -protection configuration is needed: +fall back to a focused stage's glossary list. In the party/spells scenario, no +operator protection configuration is needed: | Stage | Glossary input | Protection selection | Effective protected vocabulary | | --- | --- | --- | --- | @@ -148,12 +183,12 @@ protection configuration is needed: The table assumes distinct party and spell vocabulary. The subtraction applies after resolving both stage selections, including explicit protection overrides. It operates on recognized terms using the protection matcher's rules, including -names, aliases, and supported plural forms, rather than subtracting file paths. -Terms shared across files therefore participate in the same operation; shared -spellings associated with different identities remain part of the overlap -decision below. +names, aliases, and supported plural forms, rather than subtracting configuration +source files or collection names. Terms shared across collections participate in +the same operation; shared spellings associated with different identities remain +part of the overlap decision below. -Keep the configured protection file list intact and construct the reduced +Keep the configured protection selection intact and construct the reduced vocabulary separately for that stage. Do not mutate root settings, loaded glossary entries, or another stage's protection. A glossary stage selecting all of its protected vocabulary as active input has no glossary-derived protection @@ -172,7 +207,7 @@ Use the active-term exemption for glossary correction and retain the existing module-appropriate allowance for spoken-word cleanup. Carry both selections through execution and validation rather than passing a single combined glossary to every consumer. -Combined-entry conflicts and overlapping protected identities remain open below. +Collection identity, runtime overlap, and payload details remain open below. ### Validation-Profile Fallback — Resolved @@ -212,7 +247,6 @@ zero repairs is valid, while a zero operation timeout is invalid. | `context.description: ""` | Clear the inherited description. | | `glossaries: []` | Clear correction/context inputs; a glossary-correction stage then lacks its required input. | | `protected_terms: []` | Disable glossary-derived protection without changing correction/context inputs. | -| Empty file-path entry in either list | Error: an empty string is not a valid glossary path. | | `llm.validation_profile: null` | Clear the inherited selection, then use the effective proposal profile. | | `llm.validation_profile: ""` | Error: use null to clear the selection deliberately. | | Empty or null proposal profile | Invalid for a stage requiring model execution. | @@ -220,8 +254,9 @@ zero repairs is valid, while a zero operation timeout is invalid. Declare genuinely optional selectors nullable and preserve omission versus explicit null through resolution. Null is not a universal reset operation; -settings groups are not nullable. The glossary settings are sequences with `[]` -as their explicit-clearing form; list-null handling remains open below. +settings groups are not nullable. Preserve explicit empty selection semantics +(`[]` for list selectors) in the final glossary schema; null handling remains open +below. This concerns stage selections, not ConfigKit-owned definition collections. Reject a glossary-correction stage's missing or empty effective input before execution. Other stages may operate without glossary context where their operation supports it, independently of their protection selection. @@ -241,16 +276,16 @@ values and clearing remain authoritative for that stage. Apply validation-profil fallback after combining these selections. This preserves deliberate differences between stages while allowing invocation-specific changes to their defaults. -For the pipeline example above, a CLI assignment replacing root `glossaries` -with `[revised-party.yml, spells.yml]` changes grammar's inherited input and, -with root `protected_terms` omitted, the derived protection inherited by all -three stages. The explicit party and spell correction selections stay unchanged. +For the party/spells scenario, a CLI assignment changing the root glossary +selection changes grammar's inherited input and, with root `protected_terms` +omitted, the derived protection inherited by all three stages. The explicit party +and spell correction selections stay unchanged. An explicit root protection list is not changed by a root glossary assignment; an explicit stage protection list or `[]` remains authoritative for that stage. Apply this precedence consistently to all stage-capable settings. Submit only explicitly supplied CLI values to ConfigKit; preserve false, zero, and empty -values under their per-field rules rather than -allowing parser defaults to override configuration. +values under their per-field rules rather than allowing parser defaults to +override configuration. Keep CLI functionality within ConfigKit's native capabilities. ConfigKit v1.1.0 does not support sequence-index paths in its CLI override API, so targeted-stage @@ -262,34 +297,6 @@ The open stage-identity decision concerns reporting and diagnostics; stage IDs do not imply CLI targeting. Audita's domain-specific inheritance and fallback rules remain within ConfigKit's supported application-resolution lifecycle. -### Relative Paths and Source Context — Resolved - -ConfigKit owns configuration resolution upstream of its handoff to Audita, -including discovery, configuration source paths, imports, overlays, composition, -inheritance, and source resource contexts. Use its native behavior and public -handoff; do not reinterpret configuration paths, reload source documents, or -reconstruct its resolution rules in Audita. - -The following policy applies to glossary and protection files consumed as -application data after that handoff: - -- Resolve a relative file path supplied by configuration against the supplying - document's source resource context. -- Resolve a relative CLI file path against the invocation's working directory, - including when no main configuration file was found. -- Preserve each input path's source context through root-to-stage inheritance - and root protection defaulting. Deriving a protection list does not give its - paths a new filesystem base. - -Use ConfigKit's public origin metadata and `Result.SourceContext` to obtain the -owning filesystem and base directory, following its -[source resource contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#source-resource-contexts). -Retain source attribution through Audita's recorded derivations so each file's -original context can be identified. Honor upstream filesystem and context -semantics; do not invent a host-file base for a contextless synthetic source. -This keeps imported configuration reusable while leaving configuration loading -and resolution under ConfigKit's ownership. - ### ConfigKit Support Use the selected ConfigKit v1.1.0 public lifecycle for this work. Its @@ -300,6 +307,22 @@ nullable selectors with nullable typed fields and settings groups with non-nullable structs. Use native decoding and validation rather than a parallel parser or generic deep-merge implementation. +Use the native [collection and inheritance contracts](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#strict-document-composition) +for glossary definitions. For identified lists, register identity constraints in +Audita's ConfigKit definition so native final validation also covers values from +defaults, CLI, and recorded resolution. YAML-only declarations do not provide +that final-result guarantee. Decide identity fields and scope below. + +Compose sources in the scope where cross-source identity and inheritance are +intended to apply. Loading files separately and concatenating afterward does not +provide those upstream guarantees. Strict peers reject duplicate identities, +including identical records; higher layers follow native collection operations, +and upsert replaces a whole matching record. Empty identified collections follow +their native mode (`[]` does not clear an append/upsert collection). These rules +are distinct from Audita's whole-list replacement of ordinary stage selections. +Do not extend native inheritance beyond its supported sibling scope or treat +inherited entries as abstract templates exempt from normal validation. + Root-to-stage inheritance remains an Audita application rule: ConfigKit does not automatically copy root fields into new sequence elements. Implement that rule in `Definition.Resolve`, using `Resolution.IsExplicit` for presence and @@ -328,19 +351,25 @@ and history. Follow the native [recorded-resolution contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#recorded-application-resolution) for all derived mutations, and use `Definition.Validate` for domain checks on effective settings. Keep stage values independent when copying compound values. -No upstream feature request is presently needed for these rules. +The selected defaulting rules use existing public APIs. Verify the final glossary +composition and selection design against the native API before implementation; +do not compensate for a mismatch with a private configuration system. ### Durable Decision Record -Completion requires recording the scope model in durable documentation before -retiring this roadmap. Put the enduring classification rule and its rationale -in the [architecture policy](../policy/architecture.md); keep the implemented -per-field scope, compound-value, clearing, precedence, and fallback contracts in the -[configuration reference](../config.md). -These configuration design decisions do not require an ADR. Reserve ADRs for -major architectural decisions under the -[documentation policy](../policy/documentation.md#architecture-decision-records). -The roadmap continues to own implementation status until the feature lands. +Completion requires durable documentation before retiring this roadmap. Record +the glossary-configuration ownership boundary and typed-handoff architecture in +an ADR under the [documentation policy](../policy/documentation.md#architecture-decision-records). +This is an architectural ownership decision; routine scope and clearing choices +do not each require an ADR. The roadmap owns implementation status and sequencing. + +Put enduring scope classification and ownership rules in the +[architecture policy](../policy/architecture.md) and the implemented collection, +selection, defaulting, and clearing contracts in the +[configuration reference](../config.md). Update the glossary input contract and +consumer internals as the redesign lands, removing obsolete standalone-parser +instructions. Document the distinction between configuration identity and derived +runtime vocabulary without copying the native ConfigKit reference into Audita. Update the [configuration change guide](../internal/cli-config.md) to require classifying each new setting by consumer lifecycle, specifying its inheritance @@ -358,20 +387,25 @@ adopted configuration and CLI conventions and avoids adapting it twice. Keep the requirement visible during library design without expanding those migrations into feature implementation. -1. Apply the selected scope, glossary/protection selection, compound-value, - clearing, CLI precedence, application-resource path resolution, and - validation-profile fallback rules. Finalize remaining list-input details. Incorporate - these into the version-3 schema rather than retain the old module-name list. -2. Resolve effective stage settings and carry them through stage execution, - proposal generation, and validation. Load correction/context and protection - selections separately and settle combined-entry and identity conflicts. -3. Make repeated stages and their selected inputs understandable in inspection, - diagnostics, and reports. Account for all consumed glossary files in input - handling and output-collision protection. -4. Verify the selected behavior and update configuration, CLI, input contracts, - pipeline documentation, maintained examples, and hard-cutover guidance as the - implementation lands. Complete the durable decision record and future-setting - classification guidance above. +1. Settle the native collection/entry schema, source composition scope, stage + selection syntax, and remaining domain decisions below. Preserve the selected + scope, clearing, CLI precedence, and fallback semantics in version 3. +2. Adopt ConfigKit loading for glossary configuration. Register the selected + collection identities, supply domain validation, and deliver final typed + definitions and selections before transcript processing. Remove the redundant + standalone YAML parser and local composition path. +3. Derive rich LLM inputs, deduplicated protection vocabulary, and glossary-stage + exemptions from resolved configuration. Route the appropriate views through + proposal generation and validators without mutating configuration or other + stages. Preserve source attribution for diagnostics and inspection. +4. Verify native composition and the domain behavior together. Account for all + consumed configuration sources in input handling and output-collision + protection. Make repeated stages and their selected collections understandable + in inspection, diagnostics, and reports. +5. Update configuration, CLI, input contracts, pipeline documentation, maintained + examples, and hard-cutover guidance as implementation lands. Complete the ADR, + durable policy, and future-setting classification guidance above. No runtime + compatibility layer for the old glossary file format is required. ## Acceptance Direction @@ -389,13 +423,21 @@ glossary stage to establish that it inherits both root glossary inputs. Verify that all three stages inherit root protection derived from those inputs despite the focused correction selections. Cover explicit root and stage protection lists, independent empty-list clearing, a glossary stage with no override using -both inputs, and a file selected only on a stage not entering root protection. +both inputs, and a collection selected only on a stage not entering root protection. Verify that modules and validators receive their respective effective selections and recorded source origins. Cover repeated modules and an empty stage list. -Exercise relative glossary and protection inputs from main and imported -configuration sources and from CLI assignments, including no-main-file operation. -Verify that inherited and derived protection inputs retain their original source -context while Audita leaves ConfigKit's configuration resolution unchanged. +Exercise native glossary composition, inheritance, collection identity checks, +and supported explicit layering with reusable party/spells fixtures. Cover source +origins, strict decoding failures, and domain validation failures before processing. +Test configured discovery/no-main-file behavior through the supported load path; +do not add a secondary glossary-file resolver. Verify that inheritance and +application derivations retain traceability to their configuration inputs. + +Verify that distinct valid definitions can contribute to a deduplicated runtime +vocabulary without rewriting rich configured entries. Check that rich LLM input +contains the selected descriptive fields, and that deriving or using any runtime +view leaves configuration and other consumers' views unchanged. Verify the +selected rules for repeated membership, entry ordering, and ambiguous spellings. Exercise the selected request and validation overrides through stage consumers, including independent budgets without changing shared backend admission or the @@ -412,11 +454,11 @@ and clearing. Cover profile fallback after CLI assignment, explicit false/zero/ empty CLI values where valid, and the absence of overrides from parser defaults. Cover root protection defaulting after CLI assignment, explicit root protection surviving glossary overrides, and recorded root-to-stage protection dependencies. -Verify module-appropriate protection using terminology from both files, including +Verify module-appropriate protection using terminology from both collections, including legitimate corrections and cleanup; test the selected overlap/conflict behavior. For glossary stages, verify that active terms are exempt while remaining selected terms stay protected, including when protection was explicitly configured. -Cover names, aliases, supported plurals, and vocabulary shared across files. +Cover names, aliases, supported plurals, and vocabulary shared across collections. Verify the all-active case produces an empty effective protected vocabulary without disabling other validators. Confirm that a later non-glossary stage still protects its full selection and that inspection distinguishes configured @@ -428,21 +470,77 @@ guidance are in place before declaring this feature complete. The recommendations below are proposals, not selected contracts. -### Combined Entries and Protected Identities +### Native Collection Shape and Stage Selection -**Recommendation:** preserve declared file and entry order, coalesce identical -entries, and diagnose conflicting definitions rather than silently choosing by -file order. Define identity handling for overlapping names, aliases, and plurals -across the correction and protection selections, including how the active-term -exemption handles a shared spelling associated with different identities. This -keeps protection explainable but requires distinguishing true conflicts from -harmless repetition or legitimate shared spellings. +**Recommendation:** define named glossary collections in a typed mapping and +have root/stage selections identify those resolved collections. Use native +ConfigKit composition to populate the mapping, with minimal Audita lookup and +selection validation after structural resolution. This decouples reusable assets +from file layout and keeps focused stages concise. It requires choosing the +collection/selection field layout, membership representation, ordering, and +behavior when the same entry is selected through several collections. The exact +YAML syntax is not yet selected. -**Alternative:** use documented ordered precedence for conflicting entries. This -supports intentional local overrides and is straightforward to apply, but can -hide disagreements and make protection depend on list order. Neither approach -should accidentally inherit the existing single-glossary lookup's first-match -behavior as a new multi-file contract. +**Alternative:** embed complete glossary entry collections directly in root and +stage settings, using native inheritance and source placement for reuse. This +avoids collection-reference lookup but makes stage settings larger and reuse +subject to native sibling scopes. It can duplicate definitions and complicate +independent correction/protection selections. Neither option adds general +variable interpolation or a custom merge language. + +### Composition Scope and Reuse + +**Recommendation:** compose glossary definitions within the application's native +configuration graph before the final handoff. Treat independent sources as strict +peers and reserve intentional replacement for explicit upstream layering. This +makes cross-source identity checks, inheritance, and provenance available in the +same scope. Verify a practical import/placement layout for standalone reusable +assets; neither file-list order nor application selection should secretly create +override tiers. Standard inspection integration should follow the resulting +ConfigKit configuration rather than a second private catalog. + +**Alternative:** load isolated glossary libraries through separate ConfigKit +definitions and assemble a typed application view before processing. This can +provide useful library boundaries and independent validation, but inheritance and +identity guarantees stop at each load. Cross-library selection validation and +inspection integration would need additional application work. Do not claim that +concatenating separate results gives native cross-load composition guarantees. + +### Entry Identity and Rich Fields + +**Recommendation:** use explicit stable entry IDs independent of displayed terms, +with application-registered identity on identified lists. Choose whether identity +is global or scoped by collection and how a shared entry belongs to multiple +collections before fixing the schema. Distinct meanings can then share a spelling +without being the same record. Retain rich semantic fields for model context; +settle their names and required/optional status, including the relationship of +current `summary` to optional comment/context data. Explicit IDs add authoring +work and require clear identity scope, but survive changes to displayed terms. + +**Alternative:** use a natural key such as term plus category, or a keyed mapping +whose keys provide identity. This can reduce record ceremony and fits native +ConfigKit mechanisms, but natural keys can conflate meanings and change on rename; +mapping keys still need an intentional identity convention. Do not silently +infer semantic identity from matching text or inherit first-match lookup behavior. + +### Runtime Vocabulary and Identity Ambiguity + +**Recommendation:** deduplicate recognized spellings for protection using the +same matching rules as active-term subtraction, while retaining distinct resolved +entry identities and rich data. Repeated membership must not multiply protection. +For checks that depend on identity, do not infer equivalence or grant a relaxation +solely because entries share an alias; define conservative behavior for ambiguous +matches. Specify deterministic rich-input ordering and whether repeated selection +of the same resolved entry appears once. This preserves useful context without +turning runtime deduplication into configuration conflict resolution, but requires +focused decisions and tests around identity-dependent cleanup. + +**Alternative:** reject ambiguous names or aliases at domain validation time. +This simplifies deterministic identity checks, but disallows legitimate shared +spellings and burdens authors of reusable collections. Native ConfigKit record +identity checks remain authoritative in either case; they do not determine which +meaning a transcript occurrence has. The active-glossary exemption itself is +already selected and is not reopened by this decision. ### List Inputs and CLI Representation @@ -450,10 +548,11 @@ behavior as a new multi-file contract. ConfigKit slice decoding and presence without an additional rejection rule. Keep `[]` as the primary documented clearing form. This requires documenting a second clearing form and ensuring null suppresses protection defaulting just as `[]` -does. Select CLI syntax for supplying each complete root list using native -ConfigKit overrides. +does. After choosing the collection schema, select CLI syntax for whole root +selections using native ConfigKit overrides. These are ordinary selection lists, +not entry collections governed by native identity/operation policies. -**Alternative:** reject null for the two glossary-file lists and require `[]` for +**Alternative:** reject null for the two selection lists and require `[]` for clearing. This offers one explicit empty-list spelling but adds application validation beyond ConfigKit's nullable slice decoding. CLI spelling remains to be selected; it does not reopen root-versus-stage precedence or imply diff --git a/docs/roadmap/library-adoption.md b/docs/roadmap/library-adoption.md index 5f1049c..7b5ab14 100644 --- a/docs/roadmap/library-adoption.md +++ b/docs/roadmap/library-adoption.md @@ -12,8 +12,10 @@ and ReleaseKit so operators and maintainers encounter the same conventions across the application suite. Choose the best target state for Audita; maintaining compatibility with current behavior carries no weight in this major release. -The release also includes glossary stages that select different glossary inputs. -This is required feature scope alongside the library upgrades. +The release also includes reusable glossary configuration composed through +ConfigKit and stages that select different glossary inputs. This is required +feature scope alongside the library upgrades; the glossary roadmap owns the +configuration handoff and derived runtime representations. This document owns shared adoption principles, sequencing, dependency selection, and cross-library decisions, including the ReleaseKit adoption work below. The @@ -25,7 +27,7 @@ open decisions: | [ConfigKit](configkit.md) | Stable configuration API, loading, discovery, presence, secrets, and provenance | | [PromptKit](promptkit.md) | Native resources and bundled catalog, role integration, execution, and source accounting | | [CommandKit](commandkit.md) | Standard operator interface, configuration commands, full ckprompt inspection, and reporting | -| [Stage-Specific Glossary Inputs](glossary-stages.md) | Ordered glossary stages that select different input files | +| [Stage-Specific Glossary Inputs](glossary-stages.md) | Reusable glossary configuration, stage selections, and derived runtime vocabulary | This master roadmap and the three library outlines replace the removed `import-upgrade.md`. They retain its relevant technical evidence but supersede @@ -158,9 +160,11 @@ for Audita's complete release workflow. scope for the next major release. 5. **Add stage-specific glossary inputs.** After all four library adoptions, complete the [glossary-stage roadmap](glossary-stages.md). Use the adopted - configuration, resource, and CLI conventions to support ordered stages such - as `party.yml` followed by `spells.yml` in one processing run. This sequencing - avoids designing the feature around interfaces that the upgrades replace. + configuration and CLI conventions to compose reusable glossary assets through + ConfigKit, then derive Audita's runtime views for ordered stages such as a + party pass followed by a spell pass. Remove the standalone glossary parsing + path. This sequencing avoids designing the feature around interfaces that + the upgrades replace. 6. **Validate and document the assembled application.** Complete the offline behavioral checks from the outlines and the full Audita suite. Update canonical configuration, CLI, operations, integration, and internal documentation with