eric/audita
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Resolve extensible glossary entry content fields

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-09 03:28:30 +00:00
parent 1b76a426cc
commit 77995b7a2c
2 changed files with 64 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
docs/roadmap/configkit.md
View File

@@ -1,6 +1,6 @@
# ConfigKit Adoption Outline
**Updated:** 2026-11-08
**Updated:** 2026-11-09
**Status:** Initial outline. The [master roadmap](library-adoption.md) owns the
agreed adoption policy, reviewed versions, shared sequencing, and completion.
@@ -135,10 +135,11 @@ file remain terminal.
Supply its [optional default glossary sources](glossary-stages.md#default-sources-and-explicit-configuration--resolved)
in one underlay, with higher-priority explicit main configuration.
Register its [collection-scoped entry IDs](glossary-stages.md#entry-identity--resolved)
through native sequence identity registration.
through native sequence identity registration. Apply its
[extensible entry content contract](glossary-stages.md#entry-content-fields--resolved)
using native typed fields and inline extension data.
Complete its required durable decision record. The glossary roadmap owns
the remaining rich-field, runtime-view,
selection-input, and attribution decisions. This
the remaining runtime-view, selection-input, and attribution decisions. This
application scope model does not change native source composition or
sibling-inheritance semantics.

89
docs/roadmap/glossary-stages.md
View File

@@ -1,11 +1,11 @@
# Stage-Specific Glossary Inputs
**Updated:** 2026-11-08
**Updated:** 2026-11-09
**Status:** Accepted feature scope, ownership, and stage-selection semantics for
the next Audita major release, including named collections and recursive import
placement, optional default sources, and collection-scoped entry IDs. Rich fields,
remaining design decisions, and implementation are pending. The
placement, optional default sources, collection-scoped entry IDs, and extensible
entry content fields. Remaining design decisions and implementation are pending. The
[master roadmap](library-adoption.md) owns sequencing and release completion.
## Baseline and Target
@@ -27,8 +27,8 @@ 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. Collection placement and named selection are selected;
default import sources, their tier, and entry identity are also selected. Rich
fields, runtime ambiguity, and remaining selection details are open below.
default import sources, their tier, entry identity, and content fields are also
selected. Runtime ambiguity and remaining selection details are open below.
## Glossary Configuration Ownership — Resolved
@@ -90,11 +90,14 @@ party:
- id: merrin
name: Merrin
category: character
summary: The party's wizard.
description: The party's wizard.
player: Alex
class: wizard
level: 5
```
The `party`/`entries` nesting and explicit `id` are selected. The rich fields in
this illustration remain provisional pending the content-field decision below.
The entry follows the [selected content contract](#entry-content-fields--resolved).
Its additional campaign fields remain available for other consumers.
Keep collection identity in document keys. ConfigKit does not infer keys from
filenames or subdirectories; all matches of the declaration receive the same
@@ -138,6 +141,43 @@ whole matching record. Do not treat an identified list as a mapping that merges
individual fields of matching records. The selected ordinary stage-selection
lists remain separate from these definition collections.
### Entry Content Fields — Resolved
Require `id`, `name`, and `category` as nonempty strings. The collection-scoped
identity contract above governs `id`; `name` is the canonical term, and `category`
is free-form text rather than an Audita-defined enumeration.
Support these optional fields:
| Field | Contract |
| --- | --- |
| `description` | String providing contextual guidance; omission or an empty string requires no filler text. |
| `aliases` | List of nonempty strings representing alternate names or spellings. |
| `plural` | Nonempty string when supplied, providing an explicit plural form. |
Allow and preserve additional ordinary entry fields, including nested mappings,
lists, and scalar values. A campaign's party roster can therefore also carry
player names, classes, levels, affiliations, or data for other applications.
Preservation applies to the effective result of native composition; it does not
change whole-record replacement semantics.
Use typed Go fields for the Audita contract and ConfigKit's native inline
string-keyed map of dynamic values for unmatched fields. Its
[schema binding rules](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md#advanced-type-and-field-rules)
cover decoding and inspection without a custom decoder. Keep additional data in
the resolved Go configuration and native inspection. ConfigKit still owns its
reserved syntax and supported value shapes; extensibility does not mean
accepting arbitrary YAML. Audita validates its known fields without imposing
campaign-specific rules on additional fields. A misspelled optional field may
therefore be retained as additional data; do not add a separate typo-detection
mechanism.
Build the rich LLM projection deliberately from Audita's known glossary fields,
including `description` when present. Do not automatically forward additional
fields to the LLM. Derive protected vocabulary from names, aliases, and plurals;
unrelated metadata does not contribute vocabulary. These consumer projections
leave the complete resolved entry intact.
### Default Sources and Explicit Configuration — Resolved
Audita supplies one glossary underlay with two optional native imports:
@@ -280,7 +320,7 @@ 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. |
| Glossary module LLM | Rich entries projected from known glossary fields, including names, categories, descriptions, aliases, and plurals when present. |
| 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. |
@@ -292,7 +332,8 @@ 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.
of ambiguous identities, repeated membership, and rich-entry ordering remains
open below.
## Root Defaults and Stage Overrides — Resolved
@@ -608,9 +649,9 @@ requirement visible during library design without expanding those migrations
into feature implementation.
1. Apply named collection selection, default file/directory underlay imports,
and recursive placement. Settle entry schema, CLI selection syntax, and remaining
domain decisions below. Preserve the selected scope, clearing, CLI precedence,
and fallback semantics in version 3.
recursive placement, and the extensible entry content contract. Settle CLI
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
@@ -677,6 +718,11 @@ Allow the same ID in different collections and the same displayed name on distin
records. Verify that changing a term or description while retaining its ID targets
the same collection record, and that runtime spelling deduplication does not
collapse distinct configuration identities. Cover exact case-sensitive ID matching.
Verify required name/category validation and the optional description, aliases,
and plural contracts, including invalid types and empty values where prohibited.
Cover additional scalar, nested mapping, and list fields surviving native loading
and inspection; extension data must not mask invalid known fields. Verify that
unrelated extra fields affect neither the LLM projection nor protected vocabulary.
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.
@@ -721,23 +767,6 @@ guidance are in place before declaring this feature complete.
The recommendations below are proposals, not selected contracts.
### Entry Content Fields
**Recommendation:** retain `name`, `category`, `summary`, `aliases`, and `plural`
as the rich entry fields, with required name/category and optional descriptive
summary, aliases, and explicit plural. This keeps descriptive context available
without requiring filler text for obvious terms. Confirm field validation and
how each consumer uses optional values; the optional-summary contract would be
a deliberate change from the current glossary format. Identity is already
settled independently through `id`.
**Alternative:** rename the descriptive field to `comment` (or another selected
name) and revise requiredness as part of the major-release schema. This can align
the field with optional operator guidance rather than a formal definition, but
requires agreeing on its meaning and updating all authoring examples. Avoid
parallel interchangeable fields or an unnecessary legacy alias; compatibility
with the old format is not a constraint on the choice.
### Runtime Vocabulary and Identity Ambiguity
**Recommendation:** deduplicate recognized spellings for protection using the