18 KiB
Package cohesion and architectural boundaries audit
Reviewed at 0f34231. Audita is a single-process Go CLI. internal/cli
assembles configuration, inputs, model clients, and output destinations. Core
packages provide deterministic transcript, glossary, and configuration
operations. The framework runner coordinates module proposals, validators,
repair, and application. PromptKit integration lives in framework/llm.
Processing facts feed ordinary reports and opt-in debug artifacts.
Package map · Pipeline
The audit used the code graph for discovery and call tracing, the go list
import graph to check dependency direction, and source and tests to check what
crosses each boundary. The import inventory covered 42 internal packages,
including test support. No core package directly imports a repository package
outside internal/core. The framework imports concrete correction modules
through its production factory and built-in validator metadata through its
runner and ledger. The findings focus on the responsibilities behind those
dependencies and on implicit coupling that the import graph cannot show.
Third-party implementations were outside the review. The existing suite
passed with go test -count=1 ./... on Go 1.27.3.
Ownership policy
1. Give the validator runtime interface one owner
framework/contracts declares the interface modules expose to the runner, but
aliases its request to framework/validators.Request and returns that package's
result. framework/validators declares a second interface with the same method
set. Its request ties together candidate evidence, resolved application
settings, the LLM client, the glossary matching cache, and diagnostic writer.
The implementation package also contains the built-in deterministic rule bodies
and a switch selecting built-in validator prompts. The named validator packages
mostly construct or wrap those implementations. As a result, a module that
only needs the validator port depends on the package that implements budgeting,
model reconciliation, and concrete rule policy.
Module and validator ports ·
Validator request and result ·
Duplicate interface ·
Built-in check implementation ·
Built-in prompt selection ·
Editorial constructor
Choose one shared owner for the port, decision types, and common cardinality invariant. Give validators the evidence and collaborators they need through that boundary. Keep reusable batch construction and reconciliation in the framework, with concrete prompt selection and editorial rules owned by the built-in validators. A small first change would establish one interface and remove redundant aliases before narrowing the request. Preserve deterministic ordering and the separate full and partial cardinality rules exercised by the runner and validator tests. Interface test · Cardinality checks · Validator ownership
2. Preserve the execution class assigned to each validator decision
The metadata package provides both a registry keyed by validator name and an
instance-level execution class. The runner uses ClassOf, which prefers a
valid explicit class, to order calls and decide which calls receive LLM
interaction diagnostics. The decision record carries the name but omits the
class. The correction ledger calls ClassForKey and buckets the record into
deterministic or LLM results. An injected validator with a valid class that
differs from its name's default can therefore execute under one classification
and appear under another. The built-in registry test checks that the two agree
for built-ins. The instance-override and ledger tests exercise their respective
inputs independently. Class resolution ·
Runtime ordering ·
Decision recording ·
Ledger bucketing ·
Built-in agreement ·
Instance override ·
Ledger coverage
Treat execution class as a runtime fact. Resolve it at the runner boundary and carry it with initial and repair-revalidation decision records. The ledger can then project the class used for processing. Let the built-in registry attach default class metadata during construction. The shared validation port can own the class type and expose instance overrides. Preserve the current ledger field names and default behavior for unclassified validators.
3. Put production module construction at the composition boundary
framework/runner already takes a ModuleFactory interface. The concrete
framework/modules package imports every built-in module and installs the four
constructors in NewFactory, which the CLI selects. All four production
constructor adapters ignore their context and run spec. Configuration validates
selectable identities through the dependency-light core/modulecatalog.
Keeping the registry populated with all built-in implementations in the
framework gives a composition concern the appearance and import direction of
a reusable execution package. Runner factory port ·
Production registration ·
Constructor adapters ·
CLI composition ·
Module key catalog
Place the production factory alongside the built-in modules or in the CLI composition code, and keep the injected factory interface in runner. A small registration table can still support the existing constructor override seam. Keep the config-facing catalog free of implementation imports, and use the factory's tests to check that the catalog keys remain constructible. Module packages can continue choosing their own proposal prompts and resolving their explicit validator chains. Factory and override tests · Module contract
4. Carry one checked processing plan from preflight into execution
preflight.CheckReadiness reads configured glossary selections and lists the
required proposal and validation profiles, adding a repair profile when the
budget is enabled. The CLI supplies an inspection callback that reaches into
the concrete runtime engine to inspect the profile and its backend. Later,
executePipeline traverses the settings again and binds the same roles,
directly dereferencing profile pointers based on the earlier check. In between,
contracts.ResolveModuleRunSpecs derives instance names and the effective
glossary protection view, including the glossary module's exemptions. The
readiness and execution steps therefore agree by convention on which roles
and selections will run. Adding a role or changing when it is active requires
coordinated edits in both places.
Readiness checks ·
CLI inspection ·
Run-spec construction ·
Role binding
Have processing preparation derive the effective inputs and active role selections once. Preflight can check that plan, and composition can bind the role clients from the checked values. Keep model-facing profile inspection in the runtime adapter behind the existing narrow shape, and let preflight own the whole-pipeline readiness decision. The plan can preserve the typed resolved configuration as the provenance source. This keeps inspection independent of run readiness and preserves the requirement to reject a later unusable selection before acquiring outputs or dispatching any model work. Later-stage and repair-budget tests · Glossary and readiness ADR
5. Give glossary matching and protection a domain owner
core/glossary derives identity-aware terms and exemptions. The actual
occurrence matcher and comparisons for identity and capitalization live in
framework/validators.ProtectedVocabulary. The LLM validation context builder
uses the same type to find mentioned glossary entries. The runner also builds
the combined validator GlossaryView and extracts its protection field for
apply-time checks. Matching, change protection, and prompt-context selection
have distinct callers, but the generic matcher and the apply-time policy are
contained in the validator implementation package. Term derivation ·
Matcher and change comparison ·
Context matching ·
Runner preparation ·
Application call site
Make glossary occurrence matching and text-to-text protection assessment reusable by placing them next to glossary identity and vocabulary. Keep validator-specific evidence selection, decision reasons, prompt neighbors, and budgeting with validation. The application path should receive the protection predicate it needs and reassess against the current text. Preserve longest-match exemptions and the explicit spoken-word repetition allowance. Aligning ordinary validation and application on full-segment evidence would be a separate behavior decision. Application and exemption tests · Repetition contract · Evidence-scope finding
6. Inject interaction diagnostics at the adapter boundary
Proposal generation advertises an injectable interaction writer, yet its
production path passes a directory and constructs llm.DiagnosticsWriter
itself. It discovers redaction values by type-asserting an extra method on
its structured client. Runner validation uses a second adapter around that
writer and resolves secrets lazily. Repair constructs the concrete writer and
collects values from both repair and validation clients because its retained
payload includes validation evidence. These paths make proposal generation
and the runner know about artifact destinations and credential discovery even
though structured completion already has an explicit port.
Proposal fallback ·
Production proposal wiring ·
Validation adapter ·
Repair write ·
Repair credential sources
Give interaction capture one writer contract and let composition supply the
sink when debug is enabled. Put file naming, writes, and redaction in the
diagnostics adapter, with lazy credential sources supplied by the runtime.
Give proposal, validation, and repair callers responsibility for their own
semantic coordinates and evidence. Preserve repair's combined redaction scope
and the nonfatal result of optional write errors. The same boundary could
host debug execution projection, which currently makes processreport import
the concrete LLM observation model for a debug artifact.
Artifact writer ·
Execution debug projection ·
Proposal write-failure test ·
Repair artifact tests
7. Separate required publication from retained debug artifacts
core/diagnostics.OutputSession owns required transcript publication and
enabled report initialization and delivery. The same type also exposes
PrepareDebug, which creates a retained run directory and writes invocation
and effective-config artifacts. That method uses none of the output session
state. Preflight invokes it through the session and returns the two resources
together. This couples APIs with different lifetimes and failure semantics.
The CLI integration test exercises independently selected transcript, report,
and debug destinations. Output session ·
Debug method ·
Preflight handoff ·
Independent destinations
First expose debug setup directly through the run-directory API. Where package separation pays for itself, put the required output session in an output adapter and keep retained evidence in diagnostics. Preflight or CLI composition can still coordinate the sequence. Preserve the existing early required-output checks, independent debug selection and warnings, transcript-before-report publication, and cleanup of unpublished output. This split addresses which package owns delivery. It is compatible with sharing the regular-file staging mechanics inside that owner. Operational lifecycle · Regular-file staging finding
8. Give run-level report facts one assembly path
processreport.Build maps typed processing failures to report records and
computes counts. The CLI independently assembles the initial snapshot, derives
a failure reason and origin from runner state, then mutates status, phase,
error records, and counts during finalization. The filesystem session supplies
a formatted Kind string, so the CLI recognizes report initialization by
matching that string. For other required-output failures the report record
currently has an empty phase. Report meaning consequently depends on how the
failure reached the renderer, even though the YAML and Markdown share the
same presentation snapshot. Report assembly ·
Processing classification in CLI ·
Initial snapshot in CLI ·
Final status and error mapping ·
File failure type
Have the runner and publication adapter supply structured failure facts with
the phase and source coordinates they know, and have processreport own the
initial and final mappings to the report model. The CLI can still choose when
to finalize the run and how to present its outcome. Keep the artifact renderer
and file delivery separate so failed-output handling can render an updated
snapshot with the same record and count rules. Preserve the distinction between
unknown pre-run counts and known counts, and keep work-unit and run-level
failures independent. Delivery failure test ·
Existing phase finding ·
Report count contract
9. Put transcript conversion and output shape at their owning boundaries
schema.ParseSourceTranscriptJSON owns source decoding and preserves optional
IDs. The processing CLI converts that object to the canonical segment model,
using one-based positions for missing IDs. schema.ParseTranscriptJSONLenient
has its own copy of the conversion. On output, outputschema chooses the
format but implements only the envelope. schema.TranscriptToJSON implements
the bare form and projects the same segment fields independently. This splits
the input model transition between CLI and schema, and the public segment
encoding between schema and the output encoder registry.
CLI conversion ·
Lenient conversion ·
Bare encoder ·
Envelope encoder
Give the source-to-canonical transition a schema-level operation usable after
source acquisition, preserving the separate original source held for debug.
Let outputschema own both public envelopes and the common segment projection.
Keep parsing and normalization behavior independent of output-format choices.
Maintain separate fixtures for optional source IDs and the two public output
shapes. The current envelope test covers schema, version, and segment count,
so a compatibility refactor should verify payload fields independently as well.
Lenient ID test ·
Encoder shape tests ·
Encoding ownership