208 Commits

Author SHA1 Message Date
da5b8913d1 Migrate Audita to the v4 module path
All checks were successful
ci/woodpecker/tag/release Pipeline was successful
2026-11-17 19:57:22 +00:00
ea4e82e380 Document Go module migrations for major releases 2026-11-17 19:54:47 +00:00
8551121ef6 Prepare Audita v4 release notes and retire completed plans 2026-11-17 19:51:50 +00:00
788f830b19 Upgrade dependencies and use YAML v4 with Go 1.27.4 2026-11-17 19:48:18 +00:00
3e107bedd1 Restore fast typed decoding for ordinary transcripts 2026-11-17 12:57:47 +00:00
19755e1d47 Skip model progress after caller cancellation 2026-11-17 12:54:34 +00:00
b3ed91d593 Count repeated report write failures once 2026-11-17 12:52:34 +00:00
cc0a420722 Reuse validation facts when attributing skipped edits 2026-11-17 04:34:31 +00:00
ee1ac8fc89 Retain only reportable operation details 2026-11-17 04:31:15 +00:00
7f7aea0921 Share repair histories while debug artifacts wait for indices 2026-11-17 04:29:02 +00:00
743e64a07a Reuse complete glossary selections across matching stages 2026-11-17 04:26:44 +00:00
d26991f0bf Collect optional validation context only when it can fit 2026-11-17 04:25:35 +00:00
44c767f285 Accept equivalent integer references in model responses 2026-11-17 04:22:20 +00:00
2d93e8ae7c Reject ambiguous spans consistently across repair modes 2026-11-17 04:20:25 +00:00
9ad79ce13b Classify configuration acquisition errors consistently 2026-11-17 04:18:29 +00:00
9192239bfd Keep progress writes outside model deadlines 2026-11-17 04:17:24 +00:00
1bc54a405c Align the roadmap and runtime documentation 2026-11-17 03:57:22 +00:00
fd65d9ca1e Preserve effective transcript member values 2026-11-17 03:56:40 +00:00
a88141ef4a Use consistent reasons for typed failures 2026-11-17 03:55:29 +00:00
c6be2ec20d Preserve version one error record scopes 2026-11-17 03:54:41 +00:00
0c2a2164ec Refresh reports when delivery failures accumulate 2026-11-17 03:52:48 +00:00
f99fd993b4 Record algorithmic reliability audit findings 2026-11-17 03:49:35 +00:00
1c90fedb1e Record reliability integration audit findings 2026-11-17 02:00:31 +00:00
087e388a03 Record reliability sprint review findings 2026-11-17 01:51:41 +00:00
e8c070805e Adopt the upstream fix for malformed prompt configuration 2026-11-17 01:28:21 +00:00
a355f05a27 Verify the reliability sprint and guard release checkout validation 2026-11-16 15:19:59 +00:00
11f314d995 Report live correction progress through CommandKit 2026-11-16 15:12:06 +00:00
891d4aac2c Retain processing evidence only for selected outputs 2026-11-16 15:08:02 +00:00
5167154a1c Project typed failure origins and join correction evidence by identity 2026-11-16 15:00:05 +00:00
b98d463958 Bound concurrent section work and finalize proposal identities in order 2026-11-16 14:53:14 +00:00
1c43264f6f Commit module changes only after successful execution 2026-11-16 14:42:24 +00:00
e2710d869e Give each correction repair branch its own outcome 2026-11-16 14:36:07 +00:00
a0c70e8dce Carry one proposal result from generation to the runner 2026-11-16 14:30:57 +00:00
c2c8050bc8 Unify structured call completion and retain typed failures 2026-11-16 14:27:54 +00:00
e98e525b5c Hand checked processing selections to execution 2026-11-16 14:18:38 +00:00
b1d1b8302c Measure only the usable validation context prefix 2026-11-16 14:14:21 +00:00
0c144fd5a5 Validate internal decisions and reconcile exact model references 2026-11-16 14:11:02 +00:00
475557e4de Share edit location and check protected names in full segments 2026-11-16 04:09:25 +00:00
43ce620122 Produce the requested section count when feasible 2026-11-16 04:02:22 +00:00
27f494d4e4 Normalize nested intervals and build merges incrementally 2026-11-16 03:59:44 +00:00
f465496dd8 Keep transcript decoding and encoding on typed data 2026-11-16 03:56:54 +00:00
b63c8af467 Publish outputs to checked destinations and preserve failure evidence 2026-11-16 03:52:35 +00:00
cea7e44232 Unify optional interaction capture and warnings 2026-11-16 03:43:29 +00:00
ffe0e3491e Remove application credential substitution 2026-11-16 03:37:29 +00:00
e34672f7fe Record delegated configuration exit status gaps 2026-11-16 03:32:19 +00:00
d226bdd697 Plan the reliability and maintainability sprint 2026-11-16 03:24:06 +00:00
1d32e9bad5 Add target-state reliability and maintainability roadmap 2026-11-16 01:36:53 +00:00
730c1e4758 Record detailed processing progress decision 2026-11-16 01:24:50 +00:00
a23ce14285 Record decision to retain repair context and limits 2026-11-16 01:08:52 +00:00
073e6cea26 Record decision to preserve best-effort debug capture 2026-11-15 23:45:28 +00:00
34da87f439 Record decision to retain existing transcript input scope 2026-11-15 23:43:08 +00:00
571ad70a54 Record native backend admission decision 2026-11-15 23:38:22 +00:00
176f59b176 Record caller ownership of report destination isolation 2026-11-15 23:35:32 +00:00
747a66999f Audit credential redaction removal and simplification 2026-11-15 23:28:14 +00:00
a68a951f25 Withdraw application-wide credential redaction policy 2026-11-15 23:15:28 +00:00
42e23f8563 Assess audit findings and separate policy decisions 2026-11-15 17:52:12 +00:00
faba8abf17 Mark accepted Go limitations in the audit catalog 2026-11-15 17:22:29 +00:00
72cc24030e Consolidate and prioritize repository audit findings 2026-11-15 17:18:54 +00:00
fb6cb49ba6 Record dead code and obsolete functionality audit findings 2026-11-15 17:12:34 +00:00
9110aedcd7 Record package cohesion and boundary audit findings 2026-11-15 17:00:22 +00:00
0f34231f46 Record behavioral equivalence audit findings 2026-11-15 14:53:11 +00:00
7d064a6d5a Record test coverage and effectiveness audit findings 2026-11-15 14:40:45 +00:00
416cdea625 Record security audit findings 2026-11-15 14:26:46 +00:00
27e58fabf0 Record error handling audit findings 2026-11-15 14:17:12 +00:00
4ecb71c741 Record resource management audit findings 2026-11-15 04:01:50 +00:00
e4e5dd74e3 Record concurrency audit findings 2026-11-15 03:35:07 +00:00
c0193df387 Record maintainability and complexity audit findings 2026-11-15 03:09:51 +00:00
717d59c3b0 Record algorithmic correctness and efficiency audit 2026-11-15 03:00:28 +00:00
0eca7b85d8 Record functional correctness audit findings 2026-11-15 02:50:39 +00:00
c4ccd7897e Clarify prompt boundaries and enforce repair decisions 2026-11-15 02:41:32 +00:00
e183708021 Remove completed prompt quality plans 2026-11-15 02:31:59 +00:00
5277a1ca19 Record integrated prompt quality verification 2026-11-15 01:47:05 +00:00
6124162c7b Record validator evidence and repair execution findings 2026-11-15 01:46:20 +00:00
0ef7aca294 Clarify grammar focus in correction repair conversations 2026-11-15 01:45:39 +00:00
dfdc6cc2c4 Finish PromptKit repair and execution accounting follow-ups 2026-11-15 01:44:01 +00:00
d6413b3996 Plan the prompt quality sprint 2026-11-15 01:42:04 +00:00
fc607cfdf0 Add PromptKit review follow-ups to the plan 2026-11-15 01:36:43 +00:00
d98d419b36 Adopt PromptKit v0.23.0 conversations and execution accounting 2026-11-15 01:25:55 +00:00
d28b560265 Plan full PromptKit v0.23.0 adoption 2026-11-15 01:11:58 +00:00
f42573f8b0 Improve prompt roles and correction repair context 2026-11-11 17:42:30 +00:00
cf1fbe5748 Replace prompt quality roadmap with next improvements 2026-11-11 17:26:22 +00:00
d155bf4cb3 Remove confidence scoring and refine correction prompts 2026-11-11 17:05:52 +00:00
bbf89bb4f5 Add final test policy review to prompt quality roadmap 2026-11-11 16:52:56 +00:00
7c567d8d8b Consolidate prompt quality roadmap into implementation sequence 2026-11-11 16:46:55 +00:00
d15d80c79f Preserve narrowly tuned meaning reversal validation 2026-11-11 16:42:28 +00:00
2712a3887f Retain English defaults and plan broader prompt examples 2026-11-11 15:58:32 +00:00
6e30054c36 Clarify ongoing reevaluation of module defaults 2026-11-11 15:53:46 +00:00
2261a38a6b Record empirical basis for repeated glossary passes 2026-11-11 15:51:30 +00:00
2b5b0d6051 Retain grammar naming and clarify its planned description 2026-11-11 15:43:26 +00:00
03d1884bfb Defer editorial quality evaluation 2026-11-11 15:41:23 +00:00
5aca3ebccf Plan prompt revisions ahead of evaluation evidence 2026-11-11 15:33:08 +00:00
6a843481d2 Plan removal of confidence throughout correction workflow 2026-11-11 15:18:20 +00:00
d2eb5a5662 Record validator rejection feedback decision 2026-11-11 14:59:10 +00:00
2be7bbc015 Adopt the updated repository policies 2026-11-11 14:44:06 +00:00
64e5d0d275 Record intentional editorial acceptance across modules 2026-11-11 14:19:06 +00:00
ca36c3e319 Outline prompt quality discussion roadmap 2026-11-11 14:05:20 +00:00
6d34602f0a Remove completed correction repair planning documents 2026-11-11 13:52:42 +00:00
891c204e8f Identify the protected alias affected by a proposed edit 2026-11-11 12:34:20 +00:00
73ef2c6083 Select protected spelling findings without sorting 2026-11-11 12:31:44 +00:00
04e0c2f913 Keep detailed correction repair history in debug runs 2026-11-11 12:31:08 +00:00
6b724fd3cc Index applied changes for repair outcomes 2026-11-11 12:29:42 +00:00
8c93f728c0 Index initial repair findings and compact filtering once 2026-11-11 12:28:42 +00:00
5d90478f70 Share section lookups and replacement previews across validators 2026-11-11 12:28:00 +00:00
45b42a2689 Preserve cache settings in repair conversation replay 2026-11-11 12:26:27 +00:00
8267eba6a5 Retain application skip reasons for repaired proposals 2026-11-11 12:25:15 +00:00
bcce4729e1 Attribute filtered revisions to their repair attempts 2026-11-11 12:24:32 +00:00
d3a9edb29d Record correction repair scaling findings 2026-11-11 12:18:54 +00:00
d3fbddce11 Record correction repair integration findings 2026-11-11 12:11:36 +00:00
e029730c79 Record correction repair review findings 2026-11-11 12:02:36 +00:00
aa8073cab1 Validate correction repair through the processing command 2026-11-11 04:47:43 +00:00
f4c638313e Retain repair diagnostics and correction lineage 2026-11-11 04:37:52 +00:00
735dfc1834 Report correction repair operations and outcomes 2026-11-11 04:31:44 +00:00
d927c61199 Repair rejected corrections in independent branches 2026-11-11 04:29:18 +00:00
a5003a1e52 Collect independent correction validation findings 2026-11-11 04:23:34 +00:00
9fd36001b4 Configure correction repair profiles and budgets 2026-11-11 04:20:23 +00:00
00848203d7 Carry proposal exchanges into repair replay 2026-11-11 04:18:05 +00:00
eb45d0b623 Add module correction repair prompts 2026-11-11 04:13:55 +00:00
bb81354e21 Define correction repair response and conversation replay 2026-11-11 04:11:34 +00:00
93a080059d Plan correction repair implementation 2026-11-11 04:00:47 +00:00
b036336e2a Clarify correction repair limits and reporting 2026-11-11 03:48:30 +00:00
4f525e07cc Record accepted correction repair decisions 2026-11-11 03:36:26 +00:00
d91bb658c9 Plan correction repair after validation 2026-11-11 00:05:04 +00:00
8946a82407 Remove completed roadmaps and implementation plans 2026-11-10 20:52:52 +00:00
791deca3cd Skip application for sections without approved edits 2026-11-10 20:50:50 +00:00
c86f4fa416 Record completion of the interrupted ledger fix 2026-11-10 20:49:53 +00:00
2140314d40 Index interrupted ledger evidence by stage and proposal 2026-11-10 20:49:38 +00:00
71a9b1f560 Skip report and debug work for disabled outputs 2026-11-10 20:48:32 +00:00
a9b7c37a7e Reuse validation costs when fitting and batching 2026-11-10 20:45:38 +00:00
c16d61e091 Reuse prepared glossary data across stage sections 2026-11-10 20:42:28 +00:00
8ad27e8368 Avoid repeated glossary selection and membership work 2026-11-10 20:39:00 +00:00
1fd95abe95 Reuse credential discovery and diagnostic redactors 2026-11-10 20:37:52 +00:00
bb63c2cb10 Collect prompt file paths from effective configuration 2026-11-10 20:35:35 +00:00
7710101da0 Keep match boundaries for exempt glossary names 2026-11-10 20:33:24 +00:00
50940083c8 Preserve transcript destinations that change type 2026-11-10 20:31:03 +00:00
8a2a19ccd3 Mask padded credentials as sent to providers 2026-11-10 20:29:59 +00:00
bbac312b32 Honor cancellation before transcript delivery 2026-11-10 20:28:41 +00:00
56d39fca80 Clarify migration and subprocess failure guidance 2026-11-10 20:27:26 +00:00
9a52c8c246 Remove retired reporting and diagnostic code 2026-11-10 20:26:43 +00:00
a0e45c8f92 Show stage labels as literal Markdown text 2026-11-10 20:24:18 +00:00
bae96e5dd5 Load prompt configuration comparison sides independently 2026-11-10 20:22:23 +00:00
803effc6ea Show configuration findings when processing cannot start 2026-11-10 20:21:11 +00:00
45e5b381f5 Separate glossary context from prompt protection 2026-11-10 20:18:47 +00:00
a8eb5aea4d Resolve linked prompts in their host context 2026-11-10 20:17:54 +00:00
af0f9ac960 Keep failed processing reports consistent 2026-11-10 20:16:59 +00:00
3eacb33eb0 Record the algorithmic audit findings 2026-11-10 20:12:35 +00:00
88e166e3b1 Record the library integration audit findings 2026-11-10 18:51:12 +00:00
fa4f891689 Record the library adoption review findings 2026-11-10 18:41:23 +00:00
2844ce7e6a Complete assembled validation and migrate remaining tests 2026-11-10 18:13:12 +00:00
ba1d5d2367 Document the new configuration and processing workflow 2026-11-10 17:52:14 +00:00
926fa26a31 Identify pipeline entries in reports and diagnostics 2026-11-10 17:37:41 +00:00
7efa07ee9d Run ordered processing with independent settings 2026-11-10 17:33:30 +00:00
89de2a7014 Derive independent glossary context and protection 2026-11-10 17:25:08 +00:00
d42e2095d7 Resolve pipeline settings and collection selections 2026-11-10 17:18:30 +00:00
0a21ee2b50 Compose glossary collections through configuration 2026-11-10 17:14:31 +00:00
199c1d1dbe Connect processing preflight and output reporting 2026-11-10 17:12:28 +00:00
852e79405f Prepare and finalize output resources safely 2026-11-10 17:03:10 +00:00
8e1e073731 Enable prompt preview validation and smoke commands 2026-11-10 16:59:28 +00:00
8cc298d092 Adopt native command routing and inspection 2026-11-10 16:55:56 +00:00
50257ac554 Use native request execution and credential masking 2026-11-10 16:50:29 +00:00
497a1a18c5 Load bundled and operator prompt resources 2026-11-10 16:13:53 +00:00
7c64592cab Introduce the version three configuration loader 2026-11-10 16:08:53 +00:00
b500b855c6 Update toolchain and release integration 2026-11-10 16:02:17 +00:00
40420a217a Align adoption plans with main-relative loading releases 2026-11-10 15:49:05 +00:00
0c7622375f Plan the Audita adoption sprint 2026-11-09 16:03:16 +00:00
4920393204 Specify automatic PromptKit source discovery 2026-11-09 15:49:42 +00:00
866e4b9b23 Resolve output failures and preflight resource preparation 2026-11-09 15:25:57 +00:00
547be2d9ab Resolve ReleaseKit workflow and validator selection 2026-11-09 15:02:35 +00:00
f1fced498a Select CommandKit v0.6.0 and close the release gate 2026-11-09 14:18:34 +00:00
97f6f48098 Record remaining adoption and output-failure decisions 2026-11-09 14:02:56 +00:00
267aca4b76 Specify the Audita preflight package boundary 2026-11-09 13:37:25 +00:00
d539c06f45 Plan Audita preflight checks for empty glossary stages 2026-11-09 13:35:11 +00:00
5c69377563 Exempt active glossary spellings from overlapping protection 2026-11-09 13:22:16 +00:00
098401f674 Resolve optional stage IDs and reporting attribution 2026-11-09 12:55:46 +00:00
f016471880 Resolve glossary list clearing and configuration handoff 2026-11-09 12:53:18 +00:00
7e9bf6f149 Resolve glossary runtime views while retaining business logic 2026-11-09 12:06:53 +00:00
77995b7a2c Resolve extensible glossary entry content fields 2026-11-09 03:28:30 +00:00
1b76a426cc Resolve collection-scoped glossary entry identities 2026-11-09 02:45:50 +00:00
607fefac47 Select optional glossary file and directory underlay imports 2026-11-09 02:41:11 +00:00
6908dcd206 Document shared glossary libraries and campaign composition 2026-11-08 22:59:55 +00:00
42930d4921 Select named glossary collections with recursive directory imports 2026-11-08 21:07:15 +00:00
64786140e8 Plan ConfigKit glossary composition and derived runtime views 2026-11-08 18:51:37 +00:00
af6f62e14b Resolve glossary paths at the ConfigKit application handoff 2026-11-08 17:09:52 +00:00
167d91131e Exempt active glossary vocabulary from stage protection 2026-11-08 16:26:08 +00:00
4019f57eaa Plan separate glossary and protection lists with root defaulting 2026-11-08 16:11:32 +00:00
760a7cecc0 Resolve stage CLI precedence within native ConfigKit capabilities 2026-11-08 15:34:20 +00:00
943152d1d5 Resolve compound stage settings and explicit clearing rules 2026-11-08 15:27:39 +00:00
c94086048a Adopt upstream ADR guidance and revise durable documentation requirements 2026-11-08 15:18:38 +00:00
d2c0e22a9a Resolve stage setting scope and validation profile fallback 2026-11-08 15:07:13 +00:00
0b3734d352 Plan root defaults and independent stage overrides 2026-11-08 14:58:37 +00:00
b7bad87659 Select application schema version 3 with a hard cutover 2026-11-08 14:48:51 +00:00
c46a689e29 Resolve standard request commands and upstream documentation ownership 2026-11-08 14:42:58 +00:00
9dba2d506a Require an explicit transcript destination for quiet processing 2026-11-08 14:31:44 +00:00
68e16f6aac Resolve quiet reporting and completion summary behavior 2026-11-08 14:05:00 +00:00
1f2beef08c Gate CommandKit adoption on released shared debug binding 2026-11-08 13:56:40 +00:00
32bac58b5e Separate debug artifact capture from reporting mode 2026-11-08 13:54:35 +00:00
90d82b5b5f Resolve unified debug mode and record CommandKit API gap 2026-11-08 13:25:44 +00:00
a9dba890ba Resolve behavior when configuration discovery finds no file 2026-11-08 05:20:05 +00:00
04f9f16e27 Resolve configuration discovery order and import support 2026-11-08 05:17:43 +00:00
893f66b34b Resolve retirement of the curated profile summary 2026-11-08 05:14:48 +00:00
98ffb67432 Plan namespaced bundled prompts and operator replacements 2026-11-08 02:13:03 +00:00
ec8dffc06e Resolve native backend and credential ownership 2026-11-08 02:05:48 +00:00
d4d510a520 Resolve backend concurrency ownership and plan redundant code removal 2026-11-08 01:48:50 +00:00
ac86c77cfe Plan stage-specific glossary inputs for the next major release 2026-11-08 01:42:48 +00:00
259f728f20 Plan ReleaseKit adoption and a major-release hard cutover 2026-11-08 01:40:10 +00:00
46765bd326 Document native library adoption plans 2026-11-08 01:31:18 +00:00
cbcb1b3778 Index the v3.1.1 release notes
Some checks failed
ci/woodpecker/tag/release Pipeline failed
2026-10-11 01:56:54 +00:00
39052bf47e Write the Audita v3.1.1 release note 2026-10-11 01:55:06 +00:00
7cd5edd650 Resolve annotated tag events before CI delivery 2026-10-11 01:51:44 +00:00
290 changed files with 16307 additions and 10244 deletions

View File

@@ -1,6 +1,6 @@
matrix:
include:
- GO_IMAGE: golang:1.26.8-bookworm
- GO_IMAGE: golang:1.27.4-bookworm
when:
- event: tag
@@ -20,31 +20,33 @@ steps:
git check-ref-format "refs/tags/$${CI_COMMIT_TAG}"
git fetch origin "refs/tags/$${CI_COMMIT_TAG}:refs/tags/$${CI_COMMIT_TAG}"
tag_commit=$(git rev-parse "refs/tags/$${CI_COMMIT_TAG}^{commit}")
expected_commit=$(printf '%s' "$${CI_COMMIT_SHA}" | tr '[:upper:]' '[:lower:]')
expected_commit=$(git rev-parse --verify "$${CI_COMMIT_SHA}^{commit}")
test "$(printf '%s' "$${tag_commit}" | tr '[:upper:]' '[:lower:]')" = "$${expected_commit}"
git checkout --detach "$${tag_commit}"
test "$(git rev-parse HEAD | tr '[:upper:]' '[:lower:]')" = "$${expected_commit}"
test -z "$(git status --porcelain --untracked-files=all)"
checkout_status=$(git status --porcelain --untracked-files=all) || exit $?
test -z "$${checkout_status}"
bootstrap_dir=$(mktemp -d "$${CI_WORKSPACE%/*}/.releasekit-bootstrap.XXXXXX")
trap 'rm -rf "$${bootstrap_dir}"' EXIT
cp go.mod "$${bootstrap_dir}/go.mod"
cp go.mod "$${bootstrap_dir}/releasekit.mod"
if [ -f go.sum ]; then
cp go.sum "$${bootstrap_dir}/go.sum"
cp go.sum "$${bootstrap_dir}/releasekit.sum"
else
: > "$${bootstrap_dir}/go.sum"
: > "$${bootstrap_dir}/releasekit.sum"
fi
cp "$${bootstrap_dir}/go.mod" "$${bootstrap_dir}/releasekit.mod"
cp "$${bootstrap_dir}/go.sum" "$${bootstrap_dir}/releasekit.sum"
export GOWORK=off
export GOTOOLCHAIN=local
releasekit_module=gitea.maximumdirect.net/eric/ReleaseKit
releasekit_host_os=$(go env GOHOSTOS) || exit $?
releasekit_host_arch=$(go env GOHOSTARCH) || exit $?
export GOOS="$${releasekit_host_os}" GOARCH="$${releasekit_host_arch}"
releasekit_module=go.maximumdirect.net/releasekit
go list -mod=mod -modfile="$${bootstrap_dir}/releasekit.mod" -m "$${releasekit_module}"
go build -mod=mod -modfile="$${bootstrap_dir}/releasekit.mod" \
-o "$${bootstrap_dir}/releasekit" "$${releasekit_module}/cmd/releasekit"
"$${bootstrap_dir}/releasekit" ci-deliver \
go mod edit -modfile="$${bootstrap_dir}/releasekit.mod" -tool="$${releasekit_module}/cmd/releasekit"
go list -mod=mod -modfile="$${bootstrap_dir}/releasekit.mod" -deps "$${releasekit_module}/cmd/releasekit" > /dev/null
go tool -modfile="$${bootstrap_dir}/releasekit.mod" "$${releasekit_module}/cmd/releasekit" ci-deliver \
--repo "$${CI_WORKSPACE}" \
--prepared \
--commit "$${CI_COMMIT_SHA}" \
--commit "$${expected_commit}" \
"$${CI_COMMIT_TAG}"

View File

@@ -1,55 +1,34 @@
# Audita
Audita polishes transcript JSON using glossary-aware and LLM-backed correction
modules. It validates proposed corrections and produces corrected text plus
reports for review and subprocess integration.
Audita polishes transcript JSON with glossary-aware and LLM-backed correction
modules. It validates proposed edits and produces corrected text and reports for
review or subprocess integration.
## Quickstart
From a checkout, build with Go 1.26.0 or newer:
Build with Go 1.27.0 or newer:
```sh
go build -o ./bin/audita ./cmd/audita
```
Processing requires a reachable [compatible LLM endpoint](docs/integrations/openai-compatible-llm.md)
and access to a model you select. The [minimal config](examples/minimal-config.yml)
targets an unauthenticated local endpoint; edit its endpoint and
[local profiles](examples/profiles/local/) to match your service and models. The
[service example](examples/production-config.yml) demonstrates a named credential
reference and a shared backend. Set its referenced environment variable before
validating it. The [testing overlay](examples/overlays/testing.yml) selects both
role profiles, but model cost, speed, and quality depend on your provider choices.
Check configuration and profile selection offline:
Edit the synthetic endpoint and model in [examples/local/prompts.yml](examples/local/prompts.yml)
for a reachable OpenAI-compatible service. From `examples/local`, run the built
executable (adjust the executable path if needed):
```sh
./bin/audita config validate --config examples/minimal-config.yml
./bin/audita config print-effective --config examples/minimal-config.yml --view profiles
../../bin/audita config validate --config config.yml
../../bin/audita process --config config.yml --output corrected.json transcript.json
```
Run the included small input with the minimal config:
```sh
./bin/audita process examples/tiny-transcript.json \
--config examples/minimal-config.yml \
--glossary examples/tiny-glossary.yaml \
--output corrected.json
```
This makes LLM requests. Explicit setting flags override the selected file and
optional overlay; general environment setting overrides are no longer read.
By default the command writes `errors.yml`, `recoveries.yml`, and `report.md`
beside `corrected.json`. Use `--reporting=false` to suppress those files, or
`--debug` to retain detailed run artifacts under the configured debug work
directory. Model failures affecting some operations can still yield a completed
transcript with applied corrections; the summary and reports identify them.
See the [v2 migration guide](docs/migrations/v2.md) for old configurations.
Processing makes model requests. Reports are written beside the output by default;
recoverable model errors can appear in a completed run. The [example guide](examples/README.md)
includes service, overlay, prompt editing, preview, and shared glossary projects.
See the [v3 migration guide](docs/migrations/v3.md) for the configuration cutover.
## Documentation
- [CLI reference](docs/cli.md)
- [Configuration and maintained examples](docs/config.md)
- [CLI reference](docs/cli.md) and [configuration](docs/config.md)
- [Operations and artifact lifecycle](docs/operations.md)
- [Transcript and glossary inputs](docs/integrations/transcript-glossary-files.md)
- [Output files and report formats](docs/integrations/output-files.md)

View File

@@ -0,0 +1,405 @@
package main
import (
"bytes"
"context"
"encoding/json"
"fmt"
"net/http"
"net/http/httptest"
"os"
"os/exec"
"path/filepath"
"reflect"
"strings"
"sync"
"testing"
"time"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/reporting"
)
type repairWireMessage struct {
Role string `json:"role"`
Content string `json:"content"`
}
type repairWireRequest struct {
Messages []repairWireMessage `json:"messages"`
ResponseFormat struct {
JSONSchema struct {
Schema struct {
Properties map[string]any `json:"properties"`
} `json:"schema"`
} `json:"json_schema"`
} `json:"response_format"`
}
type correctionProvider struct {
mu sync.Mutex
requests []repairWireRequest
attempts map[int]int
entered chan struct{}
wait bool
invalidFirstRevision bool
decimalReferences bool
}
func (p *correctionProvider) ServeHTTP(w http.ResponseWriter, r *http.Request) {
var req repairWireRequest
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
http.Error(w, "bad request", 400)
return
}
_, repair := req.ResponseFormat.JSONSchema.Schema.Properties["proposal_ref"]
_, validation := req.ResponseFormat.JSONSchema.Schema.Properties["validations"]
p.mu.Lock()
p.requests = append(p.requests, req)
decimalReferences := p.decimalReferences
p.mu.Unlock()
content := `{"corrections":[{"id":1,"original_text":"hello","corrected_text":"Hello"},{"id":2,"original_text":"second","corrected_text":"Second"},{"id":3,"original_text":"third","corrected_text":"Third"}]}`
if validation {
var candidates []fixtureValidationItem
for _, message := range req.Messages {
if items, ok := fixtureValidationItems(message.Content); ok {
candidates = append(candidates, items...)
}
}
var decisions []map[string]any
for _, item := range candidates {
p.mu.Lock()
approved := item.OriginalText != "third" && (item.OriginalText != "second" || p.attempts[2] > 1)
p.mu.Unlock()
reason := ""
if !approved {
reason = "The capitalization is unsupported in the supplied context."
}
decisions = append(decisions, map[string]any{"correction_index": item.CorrectionIndex, "approved": approved, "reason": reason})
}
raw, _ := json.Marshal(map[string]any{"validations": decisions})
content = string(raw)
}
if repair {
if p.wait {
select {
case p.entered <- struct{}{}:
default:
}
<-r.Context().Done()
return
}
ref := 2
if strings.Contains(req.Messages[len(req.Messages)-1].Content, `"proposal_ref":3`) {
ref = 3
}
p.mu.Lock()
p.attempts[ref]++
attempt := p.attempts[ref]
invalid := p.invalidFirstRevision && attempt == 1
p.mu.Unlock()
if ref == 3 {
http.Error(w, `{"error":{"message":"context too long"}}`, http.StatusBadRequest)
return
}
id := 2
if invalid {
id = 99
}
content = fmt.Sprintf(`{"proposal_ref":2,"decision":{"action":"revise","correction":{"id":%d,"original_text":"second","corrected_text":"Second"}}}`, id)
}
if decimalReferences {
switch {
case repair:
content = strings.NewReplacer(`"proposal_ref":2`, `"proposal_ref":2e0`, `"id":2`, `"id":2.0`).Replace(content)
case !validation:
content = strings.Replace(content, `"id":2`, `"id":2.0`, 1)
}
}
raw, _ := json.Marshal(content)
w.Header().Set("Content-Type", "application/json")
fmt.Fprintf(w, `{"model":"fixture","choices":[{"message":{"content":%s}}]}`, raw)
}
func TestSubprocessReportsDefectOnOriginatingRepair(t *testing.T) {
for _, tc := range []struct {
budget int
outcome string
recoveries int
}{{1, "exhausted", 1}, {2, "applied", 2}} {
t.Run(tc.outcome, func(t *testing.T) {
f, provider := setupCorrectionFixture(t, tc.budget, false, false)
provider.mu.Lock()
provider.invalidFirstRevision = true
provider.mu.Unlock()
if code, _, stderr := f.run(t, true); code != 0 {
t.Fatalf("code=%d stderr=%s", code, stderr)
}
doc := f.recoveries(t)
if *doc.Summary.ProposalResponses != 1 || *doc.Summary.ProposalResponsesWithFiltering != 0 || len(doc.Recoveries) != tc.recoveries {
t.Fatalf("unexpected recoveries: %+v", doc)
}
first := doc.Recoveries[0]
want := []reporting.FilteredProposal{{ProposalIndex: 1, Reason: "invalid_target_segment_id", Count: 1}}
if first.Operation != "correction_repair" || !reflect.DeepEqual(first.FilteredProposals, want) || !reflect.DeepEqual(first.Reasons, []string{"proposals_filtered"}) {
t.Fatalf("first repair recovery: %+v", first)
}
if tc.recoveries == 2 && !reflect.DeepEqual(doc.Recoveries[1].Reasons, []string{"correction_revised"}) {
t.Fatalf("successful repair recovery: %+v", doc.Recoveries[1])
}
report, err := os.ReadFile(filepath.Join(f.dir, "report.md"))
if err != nil || !strings.Contains(string(report), fmt.Sprintf("| 1 | 1 | 1 | %d | %s |", tc.budget, tc.outcome)) {
t.Fatalf("repair outcome: %s %v", report, err)
}
})
}
}
func setupCorrectionFixture(t *testing.T, attempts int, replacement, wait bool) (processFixture, *correctionProvider) {
t.Helper()
f := newProcessFixture(t, "normal", "[grammar]")
f.setSegments(t, "hello world", "second text", "third text")
provider := &correctionProvider{attempts: map[int]int{}, entered: make(chan struct{}, 1), wait: wait}
server := httptest.NewServer(provider)
t.Cleanup(server.Close)
resources := fmt.Sprintf("profiles:\n - id: proposal\n endpoint: %s/v1\n model: fixture\n - id: validation\n endpoint: %s/v1\n model: fixture\n", server.URL, server.URL)
if replacement {
resources += "collections:\n audita:\n prompts:\n - id: modules.grammar.repair\n messages:\n - role: user\n content_file: repair.txt\n output:\n format: json\n validation_mode: json_schema\n schema_path: correction_repair.v1.json\n"
if err := os.WriteFile(filepath.Join(f.dir, "repair.txt"), []byte("OVERRIDE {{ .RepairRequestJSON }}"), 0600); err != nil {
t.Fatal(err)
}
}
if err := os.WriteFile(filepath.Join(f.dir, "prompts.yml"), []byte(resources), 0600); err != nil {
t.Fatal(err)
}
data, err := os.ReadFile(f.config)
if err != nil {
t.Fatal(err)
}
text := strings.Replace(string(data), "correction_repair_attempts: 0", fmt.Sprintf("correction_repair_attempts: %d", attempts), 1)
text += "chunking:\n target_sections: 1\n min_section_tokens: 1\nnormalization:\n max_segment_gap: 0\n"
if err := os.WriteFile(f.config, []byte(text), 0600); err != nil {
t.Fatal(err)
}
return f, provider
}
func TestSubprocessCorrectionRepairConversation(t *testing.T) {
for _, tc := range []struct {
name string
debug, replacement, decimalReferences bool
}{{"default prompt without debug", false, false, false}, {"replacement with debug and equivalent reference spellings", true, true, true}} {
t.Run(tc.name, func(t *testing.T) {
f, provider := setupCorrectionFixture(t, 2, tc.replacement, false)
provider.mu.Lock()
provider.decimalReferences = tc.decimalReferences
provider.mu.Unlock()
args := []string{"--verbose"}
if tc.debug {
args = append(args, "--debug")
}
code, stdout, stderr := f.run(t, true, args...)
if code != 0 || stdout != "" {
t.Fatalf("code=%d stdout=%s stderr=%s", code, stdout, stderr)
}
output := f.readTranscript(t, f.output)
if len(output.Segments) != 3 || output.Segments[0].Text != "Hello world" || output.Segments[1].Text != "Second text" || output.Segments[2].Text != "third text" {
t.Fatalf("transcript: %+v", output)
}
report, err := os.ReadFile(filepath.Join(f.dir, "report.md"))
if err != nil {
t.Fatal(err)
}
for _, fragment := range []string{"## Correction repair", "| 1 | 1 | 1 | 2 | applied |", "| 1 | 1 | 2 | 1 | unavailable |"} {
if !strings.Contains(string(report), fragment) {
t.Errorf("missing %q in %s", fragment, report)
}
}
doc := f.errors(t)
recoveries := f.recoveries(t)
if doc.Summary.LLMOperations == nil || *doc.Summary.LLMOperations != 10 || *doc.Summary.CorrectionsApplied != 2 || *doc.Summary.Recoveries != 1 || !reflect.DeepEqual(doc.Summary, recoveries.Summary) || !strings.Contains(stderr, "2 corrections applied; 1 work units with errors; 1 recoveries") {
t.Fatalf("counts: errors=%+v recoveries=%+v stderr=%s", doc.Summary, recoveries.Summary, stderr)
}
if len(doc.Errors) != 1 || len(doc.Errors[0].Failures) != 1 || doc.Errors[0].Failures[0].Operation != "correction_repair" || doc.Errors[0].Failures[0].Reason != "provider_failed" {
t.Fatalf("errors: %+v", doc)
}
provider.mu.Lock()
requests := append([]repairWireRequest(nil), provider.requests...)
provider.mu.Unlock()
var base []repairWireMessage
var branches [][]repairWireMessage
for _, req := range requests {
if _, ok := req.ResponseFormat.JSONSchema.Schema.Properties["corrections"]; ok {
base = req.Messages
}
if _, ok := req.ResponseFormat.JSONSchema.Schema.Properties["proposal_ref"]; ok {
branches = append(branches, req.Messages)
}
}
if len(base) != 2 || len(branches) != 3 || len(branches[0]) != 4 || len(branches[1]) != 6 || len(branches[2]) != 4 {
t.Fatalf("request lengths base=%d branches=%v", len(base), branches)
}
for _, messages := range branches {
for i := range base {
if messages[i] != base[i] {
t.Fatalf("changed prefix: %+v", messages)
}
}
if messages[2].Role != "assistant" || !strings.Contains(messages[2].Content, `"corrections"`) {
t.Fatalf("missing initial response: %+v", messages)
}
}
if branches[1][3] != branches[0][3] || branches[1][4].Role != "assistant" || strings.Contains(branches[2][3].Content, `"proposal_ref":2`) {
t.Fatalf("branch history: %+v", branches)
}
if tc.replacement && !strings.Contains(branches[0][3].Content, "OVERRIDE") {
t.Fatal("replacement not used")
}
if tc.debug {
for _, activity := range []string{"correction repair turn", "validation", "provider attempts"} {
if !strings.Contains(stderr, activity) {
t.Fatalf("missing repair progress %q: %s", activity, stderr)
}
}
_, ledger := f.debugArtifacts(t)
if len(ledger) != 3 {
t.Fatalf("ledger: %+v", ledger)
}
paths, err := filepath.Glob(filepath.Join(f.dir, "runs", "run-*", "llm-execution.json"))
if err != nil || len(paths) != 1 {
t.Fatalf("execution path: %v %v", paths, err)
}
data, err := os.ReadFile(paths[0])
if err != nil {
t.Fatal(err)
}
var execution struct {
Summary struct {
ProviderAttempts int `json:"provider_attempts"`
} `json:"summary"`
}
if err := json.Unmarshal(data, &execution); err != nil {
t.Fatal(err)
}
if got := execution.Summary.ProviderAttempts; got != len(requests) {
t.Fatalf("execution provider attempts = %d, captured requests = %d", got, len(requests))
}
}
})
}
}
func TestSubprocessRepairDisabledAndOutputSelections(t *testing.T) {
for _, tc := range []struct {
name string
reporting, debug bool
}{{"neither", false, false}, {"debug only", false, true}, {"report only", true, false}} {
t.Run(tc.name, func(t *testing.T) {
f, provider := setupCorrectionFixture(t, 0, false, false)
if !tc.reporting {
file, err := os.OpenFile(f.config, os.O_APPEND|os.O_WRONLY, 0600)
if err != nil {
t.Fatal(err)
}
fmt.Fprintln(file, "reporting:\n enabled: false")
file.Close()
}
var args []string
if tc.debug {
args = append(args, "--debug")
}
code, _, stderr := f.run(t, true, args...)
if code != 0 {
t.Fatalf("code=%d stderr=%s", code, stderr)
}
provider.mu.Lock()
requests := append([]repairWireRequest(nil), provider.requests...)
provider.mu.Unlock()
for _, req := range requests {
if _, ok := req.ResponseFormat.JSONSchema.Schema.Properties["proposal_ref"]; ok {
t.Fatal("repair request with zero budget")
}
}
_, err := os.Stat(filepath.Join(f.dir, "report.md"))
if tc.reporting != (err == nil) {
t.Fatalf("report selection: %v", err)
}
if tc.debug {
_, ledger := f.debugArtifacts(t)
if len(ledger) == 0 {
t.Fatal("debug ledger missing")
}
} else if _, err := os.Stat(filepath.Join(f.dir, "runs")); !os.IsNotExist(err) {
t.Fatalf("unexpected debug dir: %v", err)
}
})
}
}
func TestSubprocessCancellationDuringCorrectionRepair(t *testing.T) {
f, provider := setupCorrectionFixture(t, 2, false, true)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
args := []string{"-test.run=^TestProcessSubprocessHelper$", "--", "process", f.transcript, "--config", f.config, "--output", f.output, "--debug"}
command := exec.CommandContext(ctx, os.Args[0], args...)
command.Env = append(os.Environ(), "AUDITA_HELPER_PROCESS=1")
var stderr bytes.Buffer
command.Stderr = &stderr
if err := command.Start(); err != nil {
t.Fatal(err)
}
select {
case <-provider.entered:
case <-ctx.Done():
t.Fatalf("repair not reached: %v", ctx.Err())
}
if err := command.Process.Signal(os.Interrupt); err != nil {
t.Fatal(err)
}
err := command.Wait()
if ctx.Err() != nil || err == nil {
t.Fatalf("cancellation: %v ctx=%v stderr=%s", err, ctx.Err(), stderr.String())
}
if _, err := os.Stat(f.output); !os.IsNotExist(err) {
t.Fatalf("transcript published: %v", err)
}
doc := f.errors(t)
if doc.Status != reporting.StatusFailed || len(doc.Errors) == 0 {
t.Fatalf("failed report: %+v", doc)
}
data, err := os.ReadFile(filepath.Join(f.dir, "report.md"))
if err != nil || !strings.Contains(string(data), "| 1 | 1 | 1 | 1 | interrupted |") {
t.Fatalf("partial report %s %v", data, err)
}
_, ledger := f.debugArtifacts(t)
if len(ledger) == 0 {
t.Fatal("partial ledger missing")
}
}
func TestSubprocessRepairWithoutOrdinaryReporting(t *testing.T) {
for _, debug := range []bool{false, true} {
t.Run(fmt.Sprintf("debug=%t", debug), func(t *testing.T) {
f, _ := setupCorrectionFixture(t, 2, false, false)
file, err := os.OpenFile(f.config, os.O_APPEND|os.O_WRONLY, 0600)
if err != nil {
t.Fatal(err)
}
fmt.Fprintln(file, "reporting:\n enabled: false")
file.Close()
args := []string{"--verbose"}
if debug {
args = append(args, "--debug")
}
code, _, stderr := f.run(t, true, args...)
if code != 0 || !strings.Contains(stderr, "2 corrections applied; 1 work units with errors; 1 recoveries") {
t.Fatalf("code=%d stderr=%s", code, stderr)
}
if _, err := os.Stat(filepath.Join(f.dir, "report.md")); !os.IsNotExist(err) {
t.Fatalf("unexpected report: %v", err)
}
if debug {
_, ledger := f.debugArtifacts(t)
if len(ledger) != 3 {
t.Fatalf("ledger: %+v", ledger)
}
}
})
}
}

View File

@@ -2,19 +2,20 @@ package main
import (
"context"
"io"
"os"
"os/signal"
"syscall"
"gitea.maximumdirect.net/eric/audita/v3/internal/cli"
"gitea.maximumdirect.net/eric/audita/v4/internal/cli"
)
func main() {
os.Exit(run())
os.Exit(run(os.Args[1:], os.Stdout, os.Stderr))
}
func run() int {
func run(args []string, stdout, stderr io.Writer) int {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
return cli.Run(ctx, os.Args[1:], os.Stdout, os.Stderr)
return cli.Run(ctx, args, stdout, stderr)
}

View File

@@ -1,15 +1,17 @@
package main
import (
"bufio"
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"net/http/httptest"
"os"
"os/exec"
"os/signal"
"path/filepath"
"reflect"
"strconv"
@@ -19,10 +21,10 @@ import (
"testing"
"time"
"gitea.maximumdirect.net/eric/audita/v3/internal/cli"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/reporting"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema"
"gopkg.in/yaml.v3"
"gitea.maximumdirect.net/eric/audita/v4/internal/cli"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/reporting"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
"go.yaml.in/yaml/v4"
)
func TestProcessSubprocessHelper(t *testing.T) {
@@ -38,10 +40,7 @@ func TestProcessSubprocessHelper(t *testing.T) {
}
syscall.Umask(int(mask))
}
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
code := cli.Run(ctx, os.Args[i+1:], os.Stdout, os.Stderr)
stop()
os.Exit(code)
os.Exit(run(os.Args[i+1:], os.Stdout, os.Stderr))
}
}
os.Exit(2)
@@ -118,53 +117,61 @@ func (p *fixtureProvider) serve(w http.ResponseWriter, r *http.Request) {
}
if p.mode == "all-model-failure" || (p.mode == "all-validation-failure" && validation) || (p.mode == "partial-validation" && validation && validationCall == 1) || (p.mode == "repair-filter-later-failure" && !validation && proposalCall == 3) {
w.WriteHeader(http.StatusInternalServerError)
_, _ = fmt.Fprintf(w, `{"error":{"message":"provider echoed %s"}}`, p.secret)
_, _ = io.WriteString(w, `{"error":{"message":"provider unavailable"}}`)
return
}
content := `{"corrections":[{"id":1,"original_text":"hello world","corrected_text":"Hello world","confidence":0.99}]}`
content := `{"corrections":[{"id":1,"original_text":"hello world","corrected_text":"Hello world"}]}`
if p.mode == "malformed-response" {
content = `{"corrections": [`
}
if p.mode == "repair-filter-later-failure" && !validation {
if proposalCall == 1 {
content = `{"wrong":true}`
} else {
content = `{"corrections":[{"id":1,"original_text":"absent text","corrected_text":"X","confidence":0.99},{"id":1,"original_text":"hello world","corrected_text":"Hello world","confidence":0.99}]}`
content = `{"corrections":[{"id":1,"original_text":"absent text","corrected_text":"X"},{"id":1,"original_text":"hello world","corrected_text":"Hello world"}]}`
}
}
if strings.HasPrefix(p.mode, "span-") {
switch p.mode {
case "span-clean", "span-filter":
content = `{"corrections":[{"id":1,"original_text":"uh ","corrected_text":"","confidence":0.99},{"id":2,"original_text":"I I","corrected_text":"I","confidence":0.99}]}`
content = `{"corrections":[{"id":1,"original_text":"uh ","corrected_text":""},{"id":2,"original_text":"I I","corrected_text":"I"}]}`
if p.mode == "span-filter" {
content = `{"corrections":[{"id":1,"original_text":"uh ","corrected_text":"","confidence":0.99},{"id":2,"original_text":"I I","corrected_text":"I","confidence":0.99},{"id":3,"original_text":"uh","corrected_text":"","confidence":0.99}]}`
content = `{"corrections":[{"id":1,"original_text":"uh ","corrected_text":""},{"id":2,"original_text":"I I","corrected_text":"I"},{"id":3,"original_text":"uh","corrected_text":""}]}`
}
case "span-spacing":
content = `{"corrections":[{"id":1,"original_text":" ","corrected_text":" ","confidence":0.99}]}`
content = `{"corrections":[{"id":1,"original_text":" ","corrected_text":" "}]}`
case "span-negative":
content = `{"corrections":[{"id":1,"original_text":"not ","corrected_text":"","confidence":0.99}]}`
content = `{"corrections":[{"id":1,"original_text":"not ","corrected_text":""}]}`
case "span-ambiguous":
content = `{"corrections":[{"id":1,"original_text":"Mage Armor","corrected_text":"ward"}]}`
if _, repair := request.ResponseFormat.JSONSchema.Schema.Properties["proposal_ref"]; repair {
content = `{"proposal_ref":1,"decision":{"action":"withdraw","correction":null}}`
}
}
if validation {
if p.mode == "span-clean" || p.mode == "span-filter" {
content = `{"validations":[{"correction_index":1,"approved":true,"confidence":0.99,"reason":"ok"},{"correction_index":2,"approved":true,"confidence":0.99,"reason":"ok"}]}`
content = `{"validations":[{"correction_index":1,"approved":true,"reason":"ok"},{"correction_index":2,"approved":true,"reason":"ok"}]}`
} else {
content = `{"validations":[{"correction_index":1,"approved":true,"confidence":0.99,"reason":"ok"}]}`
content = `{"validations":[{"correction_index":1,"approved":true,"reason":"ok"}]}`
}
if p.mode == "span-negative" && validationCall == 2 {
content = `{"validations":[{"correction_index":1,"approved":false,"confidence":0.99,"reason":"would reverse meaning"}]}`
content = `{"validations":[{"correction_index":1,"approved":false,"reason":"would reverse meaning"}]}`
}
}
}
if strings.HasPrefix(p.mode, "decision-") && !validation {
content = `{"corrections":[{"id":1,"original_text":"teh","corrected_text":"the","confidence":0.99}]}`
content = `{"corrections":[{"id":1,"original_text":"teh","corrected_text":"the"}]}`
if p.mode == "decision-mixed" {
content = `{"corrections":[{"id":1,"original_text":"teh","corrected_text":"the","confidence":0.99},{"id":2,"original_text":"cat","corrected_text":"dog","confidence":0.99},{"id":3,"original_text":"bad","corrected_text":"good","confidence":0.99},{"id":4,"original_text":"slow","corrected_text":"fast","confidence":0.99}]}`
content = `{"corrections":[{"id":1,"original_text":"teh","corrected_text":"the"},{"id":2,"original_text":"cat","corrected_text":"dog"},{"id":3,"original_text":"bad","corrected_text":"good"},{"id":4,"original_text":"slow","corrected_text":"fast"}]}`
}
}
if validation && !strings.HasPrefix(p.mode, "span-") {
content = `{"validations":[{"correction_index":1,"approved":true,"confidence":0.99,"reason":"ok"}]}`
content = `{"validations":[{"correction_index":1,"approved":true,"reason":"ok"}]}`
if p.mode == "invalid-decision-after-repair" {
if validationCall == 1 {
content = `{"wrong":true}`
} else {
content = `{"validations":[{"correction_index":9,"approved":true,"confidence":0.99,"reason":"ok"}]}`
content = `{"validations":[{"correction_index":9,"approved":true,"reason":"ok"}]}`
}
}
}
@@ -175,13 +182,13 @@ func (p *fixtureProvider) serve(w http.ResponseWriter, r *http.Request) {
continue
}
approved := !(p.mode == "decision-mixed" && len(requestedIndices) == 4 && index == 2)
decisions = append(decisions, map[string]any{"correction_index": index, "approved": approved, "confidence": 0.99, "reason": "controlled review"})
decisions = append(decisions, map[string]any{"correction_index": index, "approved": approved, "reason": "controlled review"})
if p.mode == "decision-mixed" && len(requestedIndices) == 4 && index == 4 {
decisions = append(decisions, map[string]any{"correction_index": index, "approved": false, "confidence": 0.99, "reason": "conflicting review"})
decisions = append(decisions, map[string]any{"correction_index": index, "approved": false, "reason": "conflicting review"})
}
}
if p.mode == "decision-mixed" && len(requestedIndices) == 4 || addExtra {
decisions = append(decisions, map[string]any{"correction_index": 99, "approved": true, "confidence": 0.99, "reason": "unexpected review"})
decisions = append(decisions, map[string]any{"correction_index": 99, "approved": true, "reason": "unexpected review"})
}
raw, _ := json.Marshal(map[string]any{"validations": decisions})
content = string(raw)
@@ -191,26 +198,36 @@ func (p *fixtureProvider) serve(w http.ResponseWriter, r *http.Request) {
_, _ = fmt.Fprintf(w, `{"model":"synthetic","choices":[{"message":{"content":%s}}],"usage":{"prompt_tokens":2,"completion_tokens":3,"total_tokens":5}}`, encoded)
}
// Read the supplied candidate JSON independently of the bundled instruction prose.
type fixtureValidationItem struct {
CorrectionIndex int `json:"correction_index"`
OriginalText string `json:"original_text"`
}
func fixtureValidationItems(content string) ([]fixtureValidationItem, bool) {
for offset := 0; offset < len(content); offset++ {
if content[offset] != '[' {
continue
}
var items []fixtureValidationItem
if err := json.Unmarshal([]byte(content[offset:]), &items); err == nil && len(items) > 0 && items[0].CorrectionIndex > 0 {
return items, true
}
}
return nil, false
}
func fixtureValidationIndices(messages []struct {
Content string `json:"content"`
}) ([]int, error) {
for _, message := range messages {
const marker = "Corrections to validate:"
position := strings.LastIndex(message.Content, marker)
if position < 0 {
continue
if items, ok := fixtureValidationItems(message.Content); ok {
indices := make([]int, len(items))
for i, item := range items {
indices[i] = item.CorrectionIndex
}
return indices, nil
}
var items []struct {
CorrectionIndex int `json:"correction_index"`
}
if err := json.Unmarshal([]byte(strings.TrimSpace(message.Content[position+len(marker):])), &items); err != nil {
return nil, fmt.Errorf("decode validation request items: %w", err)
}
indices := make([]int, len(items))
for i, item := range items {
indices[i] = item.CorrectionIndex
}
return indices, nil
}
return nil, fmt.Errorf("validation request items not found")
}
@@ -221,7 +238,6 @@ type processFixture struct {
dir string
config string
transcript string
glossary string
output string
provider *fixtureProvider
server *httptest.Server
@@ -233,15 +249,10 @@ func newProcessFixture(t *testing.T, mode, modules string) processFixture {
p := &fixtureProvider{mode: mode, secret: `selected-secret-"\-123`, entered: make(chan struct{}, 1)}
server := httptest.NewServer(http.HandlerFunc(p.serve))
t.Cleanup(server.Close)
if err := os.Mkdir(filepath.Join(dir, "profiles"), 0700); err != nil {
resources := fmt.Sprintf("backends:\n - id: local\n endpoint: %s/v1\n api_key_env: AUDITA_TEST_PROVIDER_KEY\nprofiles:\n - id: proposal\n backend: local\n model: local\n - id: validation\n backend: local\n model: local\n", server.URL)
if err := os.WriteFile(filepath.Join(dir, "prompts.yml"), []byte(resources), 0600); err != nil {
t.Fatal(err)
}
for _, id := range []string{"proposal", "validation"} {
profile := fmt.Sprintf("profiles:\n %s:\n backend: local\n model: local\n timeout_seconds: 5\n", id)
if err := os.WriteFile(filepath.Join(dir, "profiles", id+".yaml"), []byte(profile), 0600); err != nil {
t.Fatal(err)
}
}
configPath := filepath.Join(dir, "config.yml")
repairs := 0
if mode == "repair-filter-later-failure" || mode == "invalid-decision-after-repair" {
@@ -250,7 +261,17 @@ func newProcessFixture(t *testing.T, mode, modules string) processFixture {
if strings.HasPrefix(mode, "span-") || strings.HasPrefix(mode, "decision-") {
repairs = 1
}
configText := fmt.Sprintf("version: 2\nbackends:\n local:\n endpoint: %s/v1\n credential: AUDITA_TEST_PROVIDER_KEY\nllm:\n proposal_profile: proposal\n validation_profile: validation\n transient_retries: 0\n repair_attempts: %d\npipeline:\n modules: %s\ndiagnostics:\n work_dir: %s\n", server.URL, repairs, modules, filepath.Join(dir, "runs"))
var stageList []string
for _, name := range strings.Split(strings.Trim(modules, "[]"), ",") {
if name = strings.TrimSpace(name); name != "" {
stageList = append(stageList, " - module: "+name)
}
}
pipeline := " stages: []\n"
if len(stageList) != 0 {
pipeline = " stages:\n" + strings.Join(stageList, "\n") + "\n"
}
configText := fmt.Sprintf("version: 3\nllm:\n proposal_profile: proposal\n validation_profile: validation\n transient_retries: 0\n correction_repair_attempts: 0\n repair_attempts: %d\npipeline:\n%sdiagnostics:\n work_dir: %s\n", repairs, pipeline, filepath.Join(dir, "runs"))
if strings.HasPrefix(mode, "span-") || strings.HasPrefix(mode, "decision-") {
configText += "validation:\n max_prompt_tokens: 4096\nchunking:\n target_sections: 1\n max_section_tokens: 8192\n min_section_tokens: 1\nnormalization:\n max_segment_gap: 0\n"
}
@@ -261,17 +282,14 @@ func newProcessFixture(t *testing.T, mode, modules string) processFixture {
if err := os.WriteFile(transcript, []byte(`[{"id":1,"speaker":"A","start":0,"end":1,"text":"hello world"}]`), 0600); err != nil {
t.Fatal(err)
}
glossary := filepath.Join(dir, "glossary.yaml")
if err := os.WriteFile(glossary, []byte("glossary:\n - name: Example\n category: product\n summary: A sample.\n"), 0600); err != nil {
t.Fatal(err)
}
return processFixture{dir: dir, config: configPath, transcript: transcript, glossary: glossary,
return processFixture{dir: dir, config: configPath, transcript: transcript,
output: filepath.Join(dir, "output.json"), provider: p, server: server}
}
func (f processFixture) run(t *testing.T, includeOutput bool, extra ...string) (int, string, string) {
t.Helper()
args := []string{"-test.run=^TestProcessSubprocessHelper$", "--", "process", f.transcript, "--config", f.config, "--glossary", f.glossary}
args := []string{"-test.run=^TestProcessSubprocessHelper$", "--", "process", f.transcript, "--config", f.config}
if includeOutput {
args = append(args, "--output", f.output)
}
@@ -293,25 +311,6 @@ func (f processFixture) run(t *testing.T, includeOutput bool, extra ...string) (
return code, stdout.String(), stderr.String()
}
func (f processFixture) runConfigView(t *testing.T, view string) (int, string, string) {
t.Helper()
command := exec.Command(os.Args[0], "-test.run=^TestProcessSubprocessHelper$", "--", "config", "print-effective", "--config", f.config, "--view", view)
command.Dir = f.dir
command.Env = append(os.Environ(), "AUDITA_HELPER_PROCESS=1", "AUDITA_TEST_PROVIDER_KEY="+f.provider.secret)
var stdout, stderr bytes.Buffer
command.Stdout, command.Stderr = &stdout, &stderr
err := command.Run()
code := 0
if err != nil {
if exit, ok := err.(*exec.ExitError); ok {
code = exit.ExitCode()
} else {
t.Fatal(err)
}
}
return code, stdout.String(), stderr.String()
}
func (f processFixture) errors(t *testing.T) reporting.ErrorsDocument {
t.Helper()
raw, err := os.ReadFile(filepath.Join(f.dir, "errors.yml"))
@@ -359,11 +358,11 @@ func (f processFixture) readTranscript(t *testing.T, path string) *schema.Transc
if err != nil {
t.Fatal(err)
}
transcript, err := schema.ParseTranscriptJSON(raw)
transcript, err := schema.ParseSourceTranscriptJSON(raw)
if err != nil {
t.Fatal(err)
}
return transcript
return transcript.Canonical()
}
func (f processFixture) debugArtifacts(t *testing.T) (*schema.Transcript, []map[string]json.RawMessage) {
@@ -724,6 +723,37 @@ func TestSubprocessAppliesWhitespaceOnlySpan(t *testing.T) {
f.assertNoStructuralRepairs(t, 3)
}
func TestSubprocessRejectsAmbiguousSpanAtTheSameBoundaryWithOrWithoutRepair(t *testing.T) {
for _, budget := range []int{0, 1} {
t.Run(fmt.Sprint(budget), func(t *testing.T) {
f := newProcessFixture(t, "span-ambiguous", "[grammar]")
f.setSegments(t, "Mage Armor and Mage Armor")
raw, err := os.ReadFile(f.config)
if err != nil {
t.Fatal(err)
}
cfg := strings.Replace(string(raw), "correction_repair_attempts: 0", fmt.Sprintf("correction_repair_attempts: %d", budget), 1)
cfg += "protected_terms: [spells]\nglossary_collections:\n spells:\n entries:\n - {id: armor, name: Mage Armor, category: spell}\n"
if err := os.WriteFile(f.config, []byte(cfg), 0600); err != nil {
t.Fatal(err)
}
if code, _, stderr := f.run(t, true, "--debug"); code != 0 {
t.Fatalf("exit %d: %s", code, stderr)
}
_, ledger := f.debugArtifacts(t)
if len(ledger) != 1 || !ledgerHasDecision(t, ledger[0], "deterministic_validator_decisions", "original_text_presence", false) ||
ledgerHasDecision(t, ledger[0], "deterministic_validator_decisions", "protected_terms", true) {
t.Fatalf("unexpected evidence: %+v", ledger)
}
if text := f.readTranscript(t, f.output).Segments[0].Text; text != "Mage Armor and Mage Armor" {
t.Errorf("ambiguous proposal changed segment to %q", text)
}
f.assertNoStructuralRepairs(t, 1+budget)
})
}
}
func TestSubprocessFiltersBlankResultAlongsideApprovedCorrections(t *testing.T) {
f := newProcessFixture(t, "span-filter", "[spoken_word]")
f.setSegments(t, "uh hello", "I I think", "uh")
@@ -775,7 +805,7 @@ func TestSubprocessRespectsNegativeMeaningReviewOnDeletion(t *testing.T) {
func TestSubprocessDefaultFileOutputAndReports(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
code, stdout, stderr := f.run(t, true)
if code != 0 || stdout != "" || !strings.HasPrefix(stderr, "Completed: 1 corrections applied; 0 work units with errors; 0 recoveries.") {
if code != 0 || stdout != "" || stderr != "" {
t.Fatalf("code=%d stdout=%q stderr=%q", code, stdout, stderr)
}
output, err := os.ReadFile(f.output)
@@ -807,7 +837,7 @@ func TestSubprocessStdoutAndSelectedReportDirectory(t *testing.T) {
t.Fatal(err)
}
code, stdout, stderr := f.run(t, false, "--report-dir", reports)
if code != 0 || !strings.Contains(stdout, "Hello world") || !strings.HasPrefix(stderr, "Completed:") {
if code != 0 || !strings.Contains(stdout, "Hello world") || stderr != "" {
t.Fatalf("code=%d stdout=%q stderr=%q", code, stdout, stderr)
}
if _, err := os.Stat(f.output); !os.IsNotExist(err) {
@@ -830,7 +860,7 @@ func TestSubprocessUsesIndependentTranscriptReportAndDebugDestinations(t *testin
}
f.output = filepath.Join(transcriptDir, "corrected.json")
code, stdout, stderr := f.run(t, true, "--report-dir", reportDir, "--debug", "--work-dir", debugDir)
if code != 0 || stdout != "" || !strings.HasPrefix(stderr, "Completed:") {
if code != 0 || stdout != "" || !strings.Contains(stderr, "Completed:") {
t.Fatalf("code=%d stdout=%q stderr=%q", code, stdout, stderr)
}
if output, err := os.ReadFile(f.output); err != nil || !bytes.Contains(output, []byte("Hello world")) {
@@ -859,42 +889,34 @@ func TestSubprocessReportingAndDebugSelections(t *testing.T) {
{false, false}, {false, true}, {true, false}, {true, true},
} {
f := newProcessFixture(t, "normal", "[grammar]")
if selection.reporting && selection.debug {
original, err := os.ReadFile(f.config)
if err != nil {
t.Fatal(err)
}
old := fmt.Sprintf("backends:\n local:\n endpoint: %s/v1\n credential: AUDITA_TEST_PROVIDER_KEY", f.server.URL)
inherited := fmt.Sprintf("backends:\n local-base:\n endpoint: %s/v1\n credential: AUDITA_TEST_PROVIDER_KEY\n concurrency: 2\n queue_capacity: 0\n local:\n extends: local-base\n concurrency: 1", f.server.URL)
updated := strings.Replace(string(original), old, inherited, 1)
if updated == string(original) {
t.Fatal("process fixture backend configuration was not found")
}
if err := os.WriteFile(f.config, []byte(updated), 0600); err != nil {
t.Fatal(err)
}
}
reportDir := filepath.Join(f.dir, "missing")
extra := []string{"--reporting=false", "--report-dir", reportDir}
extra := []string{"--verbose", "--reporting=false", "--report-dir", reportDir}
if selection.reporting {
reportDir = filepath.Join(f.dir, "selected-reports")
if err := os.Mkdir(reportDir, 0700); err != nil {
t.Fatal(err)
}
extra = []string{"--reporting=true", "--report-dir", reportDir}
extra = []string{"--verbose", "--reporting=true", "--report-dir", reportDir}
}
if selection.debug {
extra = append(extra, "--debug")
}
code, stdout, stderr := f.run(t, true, extra...)
if code != 0 || stdout != "" || !strings.HasPrefix(stderr, "Completed:") {
if code != 0 || stdout != "" || !strings.Contains(stderr, "1 corrections applied; 0 work units with errors; 0 recoveries") {
t.Fatalf("selection=%+v code=%d stdout=%q stderr=%q", selection, code, stdout, stderr)
}
output, err := os.ReadFile(f.output)
if err != nil {
t.Fatal(err)
}
summary := strings.SplitN(stderr, "\n", 2)[0]
summary := ""
for _, line := range strings.Split(stderr, "\n") {
if strings.HasPrefix(line, "Completed:") {
summary = line
break
}
}
if expectedOutput == "" {
expectedOutput, expectedSummary = string(output), summary
} else if string(output) != expectedOutput || summary != expectedSummary {
@@ -916,31 +938,7 @@ func TestSubprocessReportingAndDebugSelections(t *testing.T) {
t.Fatal(err)
}
}
if selection.reporting {
effective, err := os.ReadFile(filepath.Join(dirs[0], "effective-config.redacted.yaml"))
if err != nil {
t.Fatal(err)
}
if !strings.Contains(string(effective), f.server.URL+"/v1") || !strings.Contains(string(effective), "concurrency: 1") || !strings.Contains(string(effective), "queue_capacity: 0") || strings.Contains(string(effective), f.provider.secret) {
t.Fatalf("effective inherited settings: %s", effective)
}
origins, err := os.ReadFile(filepath.Join(dirs[0], "config-origins.yaml"))
if err != nil {
t.Fatal(err)
}
for _, want := range []string{"from: /backends/local-base/endpoint", "to: /backends/local/endpoint", "reference: /backends/local/extends"} {
if !strings.Contains(string(origins), want) {
t.Fatalf("configuration origins missing %q: %s", want, origins)
}
}
if strings.Contains(string(origins), f.provider.secret) {
t.Fatal("configuration origins exposed the resolved inherited credential")
}
code, explain, stderr := f.runConfigView(t, "explain")
if code != 0 || stderr != "" || !strings.Contains(explain, "from: /backends/local-base/endpoint") || strings.Contains(explain, f.provider.secret) {
t.Fatalf("inheritance explanation: code=%d stdout=%s stderr=%s", code, explain, stderr)
}
}
}
}
}
@@ -954,7 +952,7 @@ func boolInt(value bool) int {
func TestSubprocessAllModelFailureStillCompletes(t *testing.T) {
f := newProcessFixture(t, "all-model-failure", "[grammar, grammar]")
code, stdout, stderr := f.run(t, true)
code, stdout, stderr := f.run(t, true, "--verbose")
if code != 0 || stdout != "" || !strings.Contains(stderr, "2 work units with errors") {
t.Fatalf("code=%d stdout=%q stderr=%q", code, stdout, stderr)
}
@@ -966,14 +964,43 @@ func TestSubprocessAllModelFailureStillCompletes(t *testing.T) {
if document.Status != reporting.StatusCompleted || len(document.Errors) != 2 || document.Errors[0].Scope != "work_unit" || *document.Summary.WorkUnitsWithErrors != 2 || document.Errors[0].ModuleInstance == document.Errors[1].ModuleInstance || f.provider.callCount() != 2 {
t.Fatalf("model failure report: %+v", document)
}
if strings.Contains(stderr, f.provider.secret) {
t.Fatal("secret leaked in stderr")
}
func TestSubprocessCapturesMalformedProviderResponse(t *testing.T) {
f := newProcessFixture(t, "malformed-response", "[grammar]")
code, stdout, stderr := f.run(t, true, "--debug")
if code != 0 || f.provider.callCount() != 1 || !strings.Contains(stderr, "1 work units with errors") {
t.Fatalf("code=%d calls=%d stdout=%q stderr=%q", code, f.provider.callCount(), stdout, stderr)
}
responseCaptured := false
err := filepath.WalkDir(f.dir, func(path string, entry os.DirEntry, err error) error {
if err != nil {
return err
}
if entry.IsDir() || !strings.HasSuffix(entry.Name(), "-response-payload.json") {
return nil
}
data, err := os.ReadFile(path)
if err != nil {
return err
}
var response struct {
FinalContent string `json:"final_content"`
}
if err := json.Unmarshal(data, &response); err != nil {
return err
}
responseCaptured = responseCaptured || response.FinalContent == `{"corrections": [`
return nil
})
if err != nil || !responseCaptured {
t.Fatalf("missing malformed provider response: %v", err)
}
}
func TestSubprocessAllValidationFailureStillCompletes(t *testing.T) {
f := newProcessFixture(t, "all-validation-failure", "[grammar, grammar]")
code, stdout, stderr := f.run(t, true)
code, stdout, stderr := f.run(t, true, "--verbose")
if code != 0 || stdout != "" || !strings.Contains(stderr, "2 work units with errors") {
t.Fatalf("code=%d stdout=%q stderr=%q", code, stdout, stderr)
}
@@ -989,7 +1016,7 @@ func TestSubprocessAllValidationFailureStillCompletes(t *testing.T) {
func TestSubprocessRecoveredFilteringSurvivesLaterFailure(t *testing.T) {
f := newProcessFixture(t, "repair-filter-later-failure", "[grammar, grammar]")
code, _, stderr := f.run(t, true)
code, _, stderr := f.run(t, true, "--verbose")
if code != 0 || !strings.Contains(stderr, "1 corrections applied; 1 work units with errors; 1 recoveries") {
t.Fatalf("code=%d stderr=%q errors=%+v", code, stderr, f.errors(t))
}
@@ -1019,7 +1046,7 @@ func TestSubprocessRecoveredFilteringSurvivesLaterFailure(t *testing.T) {
func TestSubprocessRepairedInvalidDecisionsRemainAnError(t *testing.T) {
f := newProcessFixture(t, "invalid-decision-after-repair", "[grammar]")
code, _, stderr := f.run(t, true)
code, _, stderr := f.run(t, true, "--verbose")
if code != 0 || !strings.Contains(stderr, "0 corrections applied; 1 work units with errors; 0 recoveries") {
t.Fatalf("code=%d stderr=%q", code, stderr)
}
@@ -1037,7 +1064,7 @@ func TestSubprocessCancellationLeavesFailedReportsWithoutTranscript(t *testing.T
f := newProcessFixture(t, "wait-cancel", "[grammar, grammar]")
ctx, stop := context.WithTimeout(context.Background(), 5*time.Second)
defer stop()
args := []string{"-test.run=^TestProcessSubprocessHelper$", "--", "process", f.transcript, "--config", f.config, "--glossary", f.glossary, "--output", f.output}
args := []string{"-test.run=^TestProcessSubprocessHelper$", "--", "process", f.transcript, "--config", f.config, "--output", f.output}
command := exec.CommandContext(ctx, os.Args[0], args...)
command.Env = append(os.Environ(), "AUDITA_HELPER_PROCESS=1", "AUDITA_TEST_PROVIDER_KEY="+f.provider.secret)
var stderr bytes.Buffer
@@ -1054,8 +1081,9 @@ func TestSubprocessCancellationLeavesFailedReportsWithoutTranscript(t *testing.T
t.Fatal(err)
}
err := command.Wait()
if ctx.Err() != nil || err == nil {
t.Fatalf("cancellation did not stop run: %v %v stderr=%q", err, ctx.Err(), stderr.String())
var exit *exec.ExitError
if ctx.Err() != nil || !errors.As(err, &exit) || exit.ExitCode() != 1 {
t.Fatalf("interrupt did not reach the failure exit: %v %v stderr=%q", err, ctx.Err(), stderr.String())
}
if document := f.errors(t); document.Status != reporting.StatusFailed || len(document.Errors) == 0 {
t.Fatalf("cancellation report: %+v", document)
@@ -1067,7 +1095,7 @@ func TestSubprocessCancellationLeavesFailedReportsWithoutTranscript(t *testing.T
func TestSubprocessPartialValidationAndLaterStage(t *testing.T) {
f := newProcessFixture(t, "partial-validation", "[grammar, grammar]")
code, _, stderr := f.run(t, true)
code, _, stderr := f.run(t, true, "--verbose")
if code != 0 || !strings.Contains(stderr, "1 corrections applied; 1 work units with errors") {
t.Fatalf("code=%d stderr=%q", code, stderr)
}
@@ -1081,55 +1109,41 @@ func TestSubprocessPartialValidationAndLaterStage(t *testing.T) {
}
}
func TestSubprocessInvalidInputLeavesFailedReports(t *testing.T) {
func TestSubprocessInvalidInputCreatesNoOutput(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
if err := os.WriteFile(f.transcript, []byte("not JSON"), 0600); err != nil {
t.Fatal(err)
}
code, _, _ := f.run(t, true)
if code != 1 || f.provider.callCount() != 0 {
if code != 2 || f.provider.callCount() != 0 {
t.Fatalf("invalid input dispatched: code=%d calls=%d", code, f.provider.callCount())
}
if document := f.errors(t); document.Status != reporting.StatusFailed || len(document.Errors) != 1 || document.Errors[0].Scope != "run" {
t.Fatalf("failed report: %+v", document)
}
if _, err := os.Stat(f.output); !os.IsNotExist(err) {
t.Fatalf("failed transcript published: %v", err)
}
var recoveries reporting.RecoveriesDocument
if raw, err := os.ReadFile(filepath.Join(f.dir, "recoveries.yml")); err != nil {
t.Fatal(err)
} else if err := yaml.Unmarshal(raw, &recoveries); err != nil {
t.Fatal(err)
}
if recoveries.Status != reporting.StatusFailed {
t.Fatalf("recoveries status: %+v", recoveries)
}
if raw, err := os.ReadFile(filepath.Join(f.dir, "report.md")); err != nil || !bytes.Contains(raw, []byte("Status: failed")) {
t.Fatalf("Markdown status: %s %v", raw, err)
}
}
func TestSubprocessMissingInheritanceParentFailsBeforeProviderDispatch(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
original, err := os.ReadFile(f.config)
original, err := os.ReadFile(filepath.Join(f.dir, "prompts.yml"))
if err != nil {
t.Fatal(err)
}
updated := strings.Replace(string(original), " local:\n endpoint:", " local:\n extends: missing\n endpoint:", 1)
updated := strings.Replace(string(original), " - id: local\n", " - id: local\n extends: {id: missing}\n", 1)
if updated == string(original) {
t.Fatal("process fixture backend configuration was not found")
}
if err := os.WriteFile(f.config, []byte(updated), 0600); err != nil {
if err := os.WriteFile(filepath.Join(f.dir, "prompts.yml"), []byte(updated), 0600); err != nil {
t.Fatal(err)
}
code, stdout, stderr := f.run(t, true)
if code != 2 || stdout != "" || f.provider.callCount() != 0 || !strings.Contains(stderr, "referenced sibling does not exist") {
if code != 2 || stdout != "" || f.provider.callCount() != 0 {
t.Fatalf("missing parent handling: code=%d stdout=%q stderr=%q provider calls=%d", code, stdout, stderr, f.provider.callCount())
}
}
func TestSubprocessInvalidInputWritesFailedReportsToSelectedDirectory(t *testing.T) {
func TestSubprocessInvalidInputDoesNotCreateReportsInSelectedDirectory(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
if err := os.WriteFile(f.transcript, []byte("not JSON"), 0600); err != nil {
t.Fatal(err)
@@ -1139,25 +1153,13 @@ func TestSubprocessInvalidInputWritesFailedReportsToSelectedDirectory(t *testing
t.Fatal(err)
}
code, _, _ := f.run(t, true, "--report-dir", reportDir)
if code != 1 || f.provider.callCount() != 0 {
if code != 2 || f.provider.callCount() != 0 {
t.Fatalf("invalid input dispatched: code=%d calls=%d", code, f.provider.callCount())
}
raw, err := os.ReadFile(filepath.Join(reportDir, "errors.yml"))
if err != nil {
t.Fatal(err)
}
var document reporting.ErrorsDocument
if err := yaml.Unmarshal(raw, &document); err != nil {
t.Fatal(err)
}
if document.Status != reporting.StatusFailed || len(document.Errors) != 1 || document.Errors[0].Scope != "run" {
t.Fatalf("failed report: %+v", document)
}
if _, err := os.Stat(filepath.Join(reportDir, "recoveries.yml")); err != nil {
t.Fatal(err)
}
if raw, err := os.ReadFile(filepath.Join(reportDir, "report.md")); err != nil || !bytes.Contains(raw, []byte("Status: failed")) {
t.Fatalf("Markdown status: %s %v", raw, err)
for _, name := range []string{"errors.yml", "recoveries.yml", "report.md"} {
if _, err := os.Stat(filepath.Join(reportDir, name)); !os.IsNotExist(err) {
t.Fatalf("report created before preflight: %s %v", name, err)
}
}
if _, err := os.Stat(filepath.Join(f.dir, "errors.yml")); !os.IsNotExist(err) {
t.Fatalf("failed report appeared in default directory: %v", err)
@@ -1182,7 +1184,7 @@ func TestSubprocessOutputFailureBeforeModelDispatch(t *testing.T) {
func TestSubprocessOptionalDebugFailureDoesNotChangeOutcome(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
code, _, stderr := f.run(t, true, "--debug", "--work-dir", f.transcript)
if code != 0 || !strings.HasPrefix(stderr, "Completed: 1 corrections applied") || !strings.Contains(stderr, "debug directory") {
if code != 0 || !strings.Contains(stderr, "Completed: 1 corrections applied") || !strings.Contains(stderr, "work directory") {
t.Fatalf("optional debug failure changed processing: code=%d stderr=%q", code, stderr)
}
if _, err := os.Stat(f.output); err != nil {
@@ -1197,11 +1199,63 @@ func TestSubprocessTranscriptPreflightWithoutReporting(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
f.output = filepath.Join(f.dir, "missing", "output.json")
code, _, stderr := f.run(t, true, "--reporting=false")
if code == 0 || f.provider.callCount() != 0 || !strings.Contains(stderr, "transcript output parent") {
if code == 0 || f.provider.callCount() != 0 || !strings.Contains(stderr, "prepare transcript output") {
t.Fatalf("transcript preflight: code=%d calls=%d stderr=%q", code, f.provider.callCount(), stderr)
}
}
func TestSubprocessInfeasibleSectionTargetIsAnInputFailure(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
code, stdout, stderr := f.run(t, true, "--target-sections", "10")
if code != 2 || stdout != "" || f.provider.callCount() != 0 || !strings.Contains(stderr, "target_sections") {
t.Fatalf("infeasible target: code=%d stdout=%q stderr=%q calls=%d", code, stdout, stderr, f.provider.callCount())
}
if _, err := os.Stat(f.output); !os.IsNotExist(err) {
t.Fatalf("unexpected transcript output: %v", err)
}
if document := f.errors(t); document.Status != reporting.StatusFailed {
t.Fatalf("report status: %+v", document)
}
}
func TestSubprocessMissingCredentialIdentifiesRequiredEnvironmentVariable(t *testing.T) {
f := newProcessFixture(t, "success", "[grammar]")
f.provider.secret = ""
resources := filepath.Join(f.dir, "prompts.yml")
body, err := os.ReadFile(resources)
if err != nil {
t.Fatal(err)
}
body = bytes.Replace(body, []byte(" - id: proposal\n"), []byte(" - id: proposal\n api_key_required: true\n api_key_env: AUDITA_TEST_PROVIDER_KEY\n"), 1)
if err := os.WriteFile(resources, body, 0600); err != nil {
t.Fatal(err)
}
code, stdout, stderr := f.run(t, true)
if code != 1 || stdout != "" || f.provider.callCount() != 0 ||
!strings.Contains(stderr, "AUDITA_TEST_PROVIDER_KEY") || !strings.Contains(stderr, `proposal profile "proposal"`) {
t.Fatalf("missing credential: status=%d stdout=%q stderr=%q provider calls=%d", code, stdout, stderr, f.provider.callCount())
}
document := f.errors(t)
if document.Status != reporting.StatusFailed || len(document.Errors) != 1 ||
document.Errors[0].Reason != "setup_failure" || strings.Contains(document.Errors[0].Message, "AUDITA_TEST_PROVIDER_KEY") {
t.Fatalf("expected compact setup failure in ordinary report: %+v", document)
}
}
func TestSubprocessUnknownProfileFailsBeforeModelDispatchAndOutput(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
code, stdout, stderr := f.run(t, true, "--proposal-profile", "unknown")
if code != 2 || stdout != "" || f.provider.callCount() != 0 ||
!strings.Contains(stderr, "stage 1 (grammar) proposal profile") || !strings.Contains(stderr, "unknown") {
t.Fatalf("readiness: code=%d stdout=%q stderr=%q calls=%d", code, stdout, stderr, f.provider.callCount())
}
for _, path := range []string{f.output, filepath.Join(f.dir, "errors.yml")} {
if _, err := os.Stat(path); !os.IsNotExist(err) {
t.Fatalf("unexpected output at %s: %v", path, err)
}
}
}
func TestSubprocessOutputPermissionsHonorUmask(t *testing.T) {
for _, mask := range []string{"0077", "0022"} {
t.Run(mask, func(t *testing.T) {
@@ -1249,47 +1303,33 @@ func TestSubprocessWhitespaceOutputIsALiteralFile(t *testing.T) {
}
}
func TestSubprocessPathAnnouncementsAreRedacted(t *testing.T) {
func TestSubprocessAnnouncesActualOutputPaths(t *testing.T) {
for _, fail := range []bool{false, true} {
t.Run(fmt.Sprint(fail), func(t *testing.T) {
f := newProcessFixture(t, "normal", "[]")
selected, unused := "selected-path-secret", "unused-path-secret"
f.provider.secret = selected
t.Setenv("AUDITA_UNUSED_PATH_KEY", unused)
cfg, err := os.ReadFile(f.config)
if err != nil {
t.Fatal(err)
}
cfg = bytes.Replace(cfg, []byte("backends:\n"), []byte("backends:\n unused:\n endpoint: http://unused.invalid/v1\n credential: AUDITA_UNUSED_PATH_KEY\n"), 1)
if err := os.WriteFile(f.config, cfg, 0600); err != nil {
t.Fatal(err)
}
reportDir := filepath.Join(f.dir, unused)
reportDir := filepath.Join(f.dir, "reports")
if err := os.Mkdir(reportDir, 0700); err != nil {
t.Fatal(err)
}
f.output = filepath.Join(reportDir, "out.json")
debugParent := filepath.Join(f.dir, selected)
debugParent := filepath.Join(f.dir, "diagnostics")
if fail {
if err := os.WriteFile(f.transcript, []byte("invalid"), 0600); err != nil {
t.Fatal(err)
}
}
code, _, stderr := f.run(t, true, "--debug", "--work-dir", debugParent)
if (!fail && code != 0) || (fail && code != 1) {
if (!fail && code != 0) || (fail && code != 2) {
t.Fatalf("code=%d stderr=%q", code, stderr)
}
if strings.Contains(stderr, selected) || strings.Contains(stderr, unused) {
t.Fatalf("credential in stderr: %q", stderr)
if !fail && (!strings.Contains(stderr, filepath.Join(reportDir, "report.md")) || !strings.Contains(stderr, debugParent)) {
t.Fatalf("missing destination announcement: %q", stderr)
}
if !strings.Contains(stderr, "[REDACTED]") {
t.Fatalf("missing redacted announcement: %q", stderr)
}
if _, err := os.Stat(filepath.Join(reportDir, "report.md")); err != nil {
if _, err := os.Stat(filepath.Join(reportDir, "report.md")); !fail && err != nil {
t.Fatal(err)
}
dirs, err := os.ReadDir(debugParent)
if err != nil || len(dirs) != 1 {
if !fail && (err != nil || len(dirs) != 1) {
t.Fatalf("debug location: %v %v", dirs, err)
}
if !fail {
@@ -1303,7 +1343,7 @@ func TestSubprocessPathAnnouncementsAreRedacted(t *testing.T) {
func TestSubprocessInteractionWriteFailureIsVisibleAndNonfatal(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
code, _, baselineSummary := f.run(t, true)
code, _, baselineSummary := f.run(t, true, "--verbose")
if code != 0 {
t.Fatal(baselineSummary)
}
@@ -1318,16 +1358,16 @@ func TestSubprocessInteractionWriteFailureIsVisibleAndNonfatal(t *testing.T) {
t.Errorf("debug directory: %v %v", dirs, err)
return
}
if err := os.WriteFile(filepath.Join(dirs[0], "grammar"), []byte("block interaction writes"), 0600); err != nil {
if err := os.WriteFile(filepath.Join(dirs[0], "grammar_1"), []byte("block interaction writes"), 0600); err != nil {
t.Error(err)
}
}
f.provider.mu.Unlock()
code, _, stderr := f.run(t, true, "--debug")
if code != 0 || !strings.HasPrefix(stderr, strings.SplitN(baselineSummary, "\n", 2)[0]) {
if code != 0 || !strings.Contains(stderr, strings.SplitN(baselineSummary, "\n", 2)[0]) {
t.Fatalf("changed outcome: %d %q", code, stderr)
}
if !strings.Contains(stderr, "debug proposal interaction") || !strings.Contains(stderr, "debug validation interaction") {
if !strings.Contains(stderr, "proposal interaction") || !strings.Contains(stderr, "validation interaction") {
t.Fatalf("missing debug failures: %q", stderr)
}
output, err := os.ReadFile(f.output)
@@ -1360,7 +1400,7 @@ func TestSubprocessInPlaceTranscript(t *testing.T) {
t.Fatal(err)
}
if invalid {
if code != 1 || !bytes.Equal(before, after) {
if code != 2 || !bytes.Equal(before, after) {
t.Fatalf("failed processing changed input: code=%d %s", code, stderr)
}
} else if code != 0 || stdout != "" || !bytes.Contains(after, []byte("Hello world")) {
@@ -1374,15 +1414,18 @@ func TestSubprocessProfileSources(t *testing.T) {
f := newProcessFixture(t, "success", "[]")
// PromptKit uses profile IDs, not filename stems. A report-named profile is
// still an input and must not be overwritten during report initialization.
loaded := filepath.Join(f.dir, "profiles", "errors.yml")
if err := os.Rename(filepath.Join(f.dir, "profiles", "proposal.yaml"), loaded); err != nil {
if err := os.Mkdir(filepath.Join(f.dir, "prompts"), 0700); err != nil {
t.Fatal(err)
}
loaded := filepath.Join(f.dir, "prompts", "errors.yml")
if err := os.Rename(filepath.Join(f.dir, "prompts.yml"), loaded); err != nil {
t.Fatal(err)
}
before, err := os.ReadFile(loaded)
if err != nil {
t.Fatal(err)
}
f.output = filepath.Join(f.dir, "profiles", "proposal.yml")
f.output = filepath.Join(f.dir, "prompts", "proposal.yml")
code, _, stderr := f.run(t, true, "--reporting=false")
if code != 0 {
t.Fatalf("unused alternate rejected: %d %s", code, stderr)
@@ -1396,12 +1439,12 @@ func TestSubprocessProfileSources(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if code != 2 || !bytes.Equal(before, after) || f.provider.callCount() != 0 {
if code != 1 || !bytes.Equal(before, after) || f.provider.callCount() != 0 {
t.Fatalf("loaded profile not protected: %d %s", code, stderr)
}
parentDir := filepath.Join(f.dir, "profiles", "catalog")
childDir := filepath.Join(f.dir, "profiles", "nested", "child")
parentDir := filepath.Join(f.dir, "prompts", "catalog")
childDir := filepath.Join(f.dir, "prompts", "nested", "child")
for _, directory := range []string{parentDir, childDir} {
if err := os.MkdirAll(directory, 0700); err != nil {
t.Fatal(err)
@@ -1411,8 +1454,8 @@ func TestSubprocessProfileSources(t *testing.T) {
child := filepath.Join(childDir, "override.yaml")
resource := filepath.Join(parentDir, "report.md")
for path, content := range map[string]string{
parent: "prompts:\n source:\n release/1~draft:\n messages:\n - role: user\n content_file: ./report.md\n output:\n format: text\n validation_mode: basic\n",
child: "prompts:\n literal/~child:\n extends: source\n",
parent: "prompts:\n - id: source\n messages:\n - role: user\n content_file: report.md\n output:\n format: text\n validation_mode: none\n",
child: "prompts:\n - id: child\n extends: {id: source}\n",
resource: "Captured operator message.\n",
} {
if err := os.WriteFile(path, []byte(content), 0600); err != nil {
@@ -1429,7 +1472,7 @@ func TestSubprocessProfileSources(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if code != 2 || !bytes.Equal(resourceBefore, resourceAfter) || f.provider.callCount() != 0 {
if code != 1 || !bytes.Equal(resourceBefore, resourceAfter) || f.provider.callCount() != 0 {
t.Fatalf("consumed message file not protected as transcript output: %d %s", code, stderr)
}
@@ -1439,7 +1482,160 @@ func TestSubprocessProfileSources(t *testing.T) {
if err != nil {
t.Fatal(err)
}
if code != 2 || !bytes.Equal(resourceBefore, resourceAfter) || f.provider.callCount() != 0 {
if code != 1 || !bytes.Equal(resourceBefore, resourceAfter) || f.provider.callCount() != 0 {
t.Fatalf("consumed message file not protected as report output: %d %s", code, stderr)
}
}
func TestSubprocessProgressReportingModes(t *testing.T) {
for _, tc := range []struct {
name string
flags []string
visible bool
file bool
}{
{name: "ordinary"},
{name: "explicit", flags: []string{"--progress"}, visible: true},
{name: "debug", flags: []string{"--debug"}, visible: true},
{name: "debug with progress off", flags: []string{"--debug", "--progress=false"}},
{name: "quiet", flags: []string{"--quiet", "--progress"}, file: true},
} {
t.Run(tc.name, func(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
code, stdout, stderr := f.run(t, tc.file, tc.flags...)
if code != 0 {
t.Fatalf("exit %d: %s", code, stderr)
}
for _, text := range []string{"Stage 1: grammar", "chunk 1", "proposal", "validation", "provider attempts"} {
if strings.Contains(stderr, text) != tc.visible {
t.Fatalf("progress fragment %q, expected visibility %v: %s", text, tc.visible, stderr)
}
}
if tc.file {
if stdout != "" {
t.Fatalf("unexpected stdout with file output: %q", stdout)
}
} else if !json.Valid([]byte(stdout)) || !strings.Contains(stdout, "Hello world") {
t.Fatalf("stdout is not the transcript: %q", stdout)
}
})
}
}
func TestSubprocessEmitsProgressBeforeProviderReturns(t *testing.T) {
f := newProcessFixture(t, "wait-cancel", "[grammar]")
ctx, stop := context.WithTimeout(context.Background(), 5*time.Second)
defer stop()
cmd := exec.CommandContext(ctx, os.Args[0], "-test.run=^TestProcessSubprocessHelper$", "--",
"process", f.transcript, "--config", f.config, "--output", f.output, "--progress")
cmd.Env = append(os.Environ(), "AUDITA_HELPER_PROCESS=1", "AUDITA_TEST_PROVIDER_KEY="+f.provider.secret)
stderr, err := cmd.StderrPipe()
if err != nil {
t.Fatal(err)
}
if err := cmd.Start(); err != nil {
t.Fatal(err)
}
defer func() {
stop()
_ = cmd.Wait()
}()
progress := make(chan string, 1)
go func() {
scanner := bufio.NewScanner(stderr)
for scanner.Scan() {
line := scanner.Text()
if strings.Contains(line, "proposal") && strings.Contains(line, "chunk 1") {
select {
case progress <- line:
default:
}
}
}
}()
select {
case <-f.provider.entered:
case <-ctx.Done():
t.Fatal("provider was not reached")
}
select {
case line := <-progress:
if !strings.Contains(line, "grammar") || !strings.Contains(line, "started") {
t.Fatalf("progress omitted the running operation: %q", line)
}
case <-ctx.Done():
t.Fatal("proposal progress did not reach stderr while the provider was blocked")
}
if err := cmd.Process.Signal(syscall.SIGTERM); err != nil {
t.Fatal(err)
}
err = cmd.Wait()
var exit *exec.ExitError
if !errors.As(err, &exit) || exit.ExitCode() != 1 || ctx.Err() != nil {
t.Fatalf("termination did not reach the failure exit: %v", err)
}
}
type unavailableDiagnostics struct{}
func (unavailableDiagnostics) Write([]byte) (int, error) {
return 0, errors.New("progress destination failed")
}
func TestProgressDeliveryFailureKeepsCompletedProcessing(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]")
t.Setenv("AUDITA_TEST_PROVIDER_KEY", f.provider.secret)
code := cli.Run(context.Background(), []string{"process", f.transcript, "--config", f.config, "--output", f.output, "--progress"}, io.Discard, unavailableDiagnostics{})
if code != 1 {
t.Fatalf("expected CommandKit presentation failure, got %d", code)
}
output, err := os.ReadFile(f.output)
if err != nil || !bytes.Contains(output, []byte("Hello world")) {
t.Fatalf("transcript did not finish: %s, %v", output, err)
}
if doc := f.errors(t); doc.Status != reporting.StatusCompleted {
t.Fatalf("presentation changed report status: %+v", doc)
}
}
type delayedProposalProgress struct {
delay time.Duration
delayed bool
}
func (w *delayedProposalProgress) Write(p []byte) (int, error) {
if !w.delayed && bytes.Contains(p, []byte("proposal started")) {
w.delayed = true
time.Sleep(w.delay)
}
return len(p), nil
}
func TestProgressDeliveryDoesNotSpendModelDeadline(t *testing.T) {
const timeout = 500 * time.Millisecond
for _, showProgress := range []bool{false, true} {
f := newProcessFixture(t, "normal", "[grammar]")
t.Setenv("AUDITA_TEST_PROVIDER_KEY", f.provider.secret)
config, err := os.ReadFile(f.config)
if err != nil {
t.Fatal(err)
}
config = bytes.Replace(config, []byte("llm:\n"), []byte("llm:\n operation_timeout: "+timeout.String()+"\n"), 1)
if err := os.WriteFile(f.config, config, 0600); err != nil {
t.Fatal(err)
}
args := []string{"process", f.transcript, "--config", f.config, "--output", f.output}
diagnostics := &delayedProposalProgress{delay: timeout + 250*time.Millisecond}
if showProgress {
args = append(args, "--progress")
}
code := cli.Run(context.Background(), args, io.Discard, diagnostics)
output, err := os.ReadFile(f.output)
if code != 0 || err != nil || !bytes.Contains(output, []byte("Hello world")) || f.provider.callCount() != 3 {
t.Fatalf("progress=%v, exit=%d, requests=%d, output=%q, read error=%v", showProgress, code, f.provider.callCount(), output, err)
}
if diagnostics.delayed != showProgress {
t.Fatalf("progress=%v, delayed=%v", showProgress, diagnostics.delayed)
}
}
}

View File

@@ -0,0 +1,42 @@
# ADR 0002: Glossary configuration and processing readiness
**Status:** Accepted
**Date:** 2026-11-10
## Context
Operators need to reuse glossary collections across campaigns and select different
context and protected terms for each ordered correction. Configuration inspection
must remain useful without a transcript, model credentials, or a populated glossary.
A processing run must reject an unusable later correction before publishing outputs
or spending resources on earlier corrections.
## Decision
ConfigKit composes typed, named glossary collections with the application
configuration. Each pipeline entry selects context and protection independently;
Audita derives consumer views without changing the resolved configuration. For a
glossary correction, active recognized spellings are exempt from that entry's
protection view. Other protected spellings and validators remain effective.
After configuration resolution, Audita preflight checks the whole pipeline and
coordinates output preparation. It consumes the typed configuration and acquired
inputs, without reloading configuration or calling a provider. The output session
owns preparation, cleanup, and publication. See the [configuration](../config.md)
and [operations](../operations.md) contracts for current behavior.
## Alternatives considered
A separately parsed glossary per invocation would duplicate composition and make
per-entry selection and provenance harder to express. Requiring nonempty
collections in configuration validation would prevent inspection and reuse of
valid empty definitions. Preparing outputs or checking each entry only when it
runs could leave artifacts or incur model work before finding a later error.
## Consequences
Configuration and runtime views have distinct responsibilities. Inspection can
show configured selections and origins without presenting derived vocabulary as
configuration. Preflight and the output session need a clear handoff, and the
processing pipeline must carry each entry's own effective settings and identity.

View File

@@ -0,0 +1,59 @@
# ADR 0003: Module focus and editorial acceptance
**Status:** Accepted
**Date:** 2026-11-11
## Context
Audita gives each correction module a focused task. A prompt review suggested
making that task's scope an acceptance condition, because validators can accept
minor editorial changes that the proposing module was not asked to make.
The maintainer's practical testing established why this difference is deliberate.
Models persistently propose minor editorial cleanup when it is clearly warranted
in the supplied text. Instructions strict enough to suppress that cleanup also
suppress desirable edits. Enforcing exclusive module scopes would therefore
trade away useful corrections to achieve a separation that does not serve the
application's editorial goals.
## Decision
Module scope guides the corrections Audita asks a model to propose. It is not an
exhaustive boundary on acceptable edits. Minor editorial cleanup is permitted
across modules and their validators even when the proposal prompt does not
request it.
Validators must not reject an otherwise acceptable minor editorial change solely
because it falls outside the originating module's requested focus. Existing
checks for applicability, protected terms, meaning, and other domain concerns
continue to apply. This allowance does not guarantee that any particular edit
passes validation or application, nor does it authorize arbitrary rewriting.
Proposal, validation, and repair instructions may differ to serve their roles.
Their consistency should be assessed against this distinction, rather than by
requiring identical lists of allowed edits. Repair feedback should not turn
module focus into an exclusive acceptance rule.
## Alternatives considered
**Strict module-aware acceptance**, whether implemented in shared validators,
separate review definitions, or an additional scope check, would make stage
boundaries easier to describe. It is rejected because the maintainer's testing
shows that suppressing incidental cleanup also suppresses desirable work.
**Request every kind of cleanup in every module** would align proposal requests
with the broader acceptance policy, but would dilute the focused tasks. Permitting
incidental cleanup does not require asking each stage to perform every task.
## Consequences
An edit accepted outside a module's requested focus is not, by itself, a design
defect. Prompt maintenance and evaluation should preserve useful corrections
while checking substantive editorial quality. They should not introduce strict
scope enforcement as an apparent consistency fix.
The [architecture policy](../policy/architecture.md#correction-and-concurrency-invariants)
records the boundary. Reconsidering this accepted decision requires new evidence
and explicit supersession under the ADR lifecycle, rather than rediscovering the
same prompt/validator difference during each review.

View File

@@ -4,6 +4,10 @@
- [ADR 0001: Adopt ReleaseKit for release management](0001-releasekit.md) —
accepted 2026-10-07.
- [ADR 0002: Glossary configuration and processing readiness](0002-glossary-configuration-and-preflight.md) —
accepted 2026-11-10.
- [ADR 0003: Module focus and editorial acceptance](0003-module-focus-and-editorial-acceptance.md) —
accepted 2026-11-11.
Use the
[documentation policy's ADR lifecycle](../policy/documentation.md#architecture-decision-records)

View File

@@ -1,116 +1,53 @@
# Audita CLI Reference
The shared version-2 configuration parser and offline profile inspection serve
`process`, `config validate`, and `config print-effective`.
The [configuration reference](config.md) owns fields, defaults, and validation;
the [migration guide](migrations/v2.md) maps retired inputs.
Audita uses CommandKit for routing and the ConfigKit and PromptKit integrations
for their standard inspection and request commands. Run `audita --help` or
command-specific `--help` for the installed command inventory. The adopted
[CommandKit consumer guide](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/f369d6a78253b6e6fcb1e023fb2e9c3af1d20ff0/docs/consumers/guide.md)
describes the standard command grammar, inspection, comparison, preview,
validation, smoke tests, and their provider-specific caveats. Help and version
do not load application or model configuration.
## Commands and help
## Processing
```sh
audita process <transcript.json> --glossary <glossary.yml> [flags]
audita config validate --config <config.yml> [flags]
audita config print-effective [flags]
audita version
audita process [flags] transcript.json
```
Root invocation, `--help`, `-h`, and command help succeed without loading a config
file or resolving secrets. Unknown commands and flags return exit code `2`.
`process` accepts exactly one transcript path, either before the flags or after
them. With flags first, put the transcript last. Both config commands reject
positional arguments and process-only flags.
`--config` selects a main configuration and `--overlay` selects its overlay.
`--output` writes the transcript to a file; omission selects stdout. The shared
`--debug` flag enables retained debug artifacts, and `--quiet` suppresses optional
messages. Quiet processing requires an output file or `/dev/null`. See
[operations](operations.md) for output and report lifecycle.
All three commands accept `--config <path>` and `--overlay <name>`. `config validate`
requires an explicit nonempty `--config`; the other commands select the explicit
file, then `/usr/local/etc/audita/config.yml`, then `/etc/audita/config.yml`.
Missing system candidates are skipped; inaccessible selected files are errors.
No file means a configuration error. `AUDITA_CONFIG` is ignored. The selected
overlay is loaded beside the main file, not used to locate profile files.
Progress for processing goes to stderr. Use `--progress` to show stage and
chunk activity, model proposal, validation and repair operations, and observed
counts as work completes. Debug mode enables progress by default.
`--progress=false` disables it, and quiet mode suppresses it even when
`--progress` is explicit.
`audita version` prints `audita <version>` and a newline to stdout, with no
application configuration or provider setup. It returns `0` on success with
empty stderr. `help version`, `version -h`, and `version --help` print command
usage to stdout and return `0`. Help follows standard flag parsing and can
short-circuit trailing arguments. Other invalid invocations return `2` with a
usage error on stderr. The command uses ReleaseKit's public
`buildinfo.Version()` accessor. It reports an injected release identifier when
present, otherwise the executable's main-module version when available and not
`(devel)`, and `dev` when neither source provides a release identifier.
Explicit process flags override root settings only. `--glossaries` and
`--protected-terms` each accept one JSON array of collection names or `null`;
`[]` clears the selection. Set pipeline order and per-entry overrides in YAML.
Other supplied flags cover profiles, output schema, description, reporting,
chunking, normalization, validation budget, and debug
work directory. `audita process --help` lists the available flags. An omitted flag
does not contribute an override. [Configuration](config.md) defines their values
and inheritance.
## Setting overrides
## Inspection and outcomes
Only flags actually supplied override file or overlay settings. `--modules ''`
clears the module pipeline, and an explicit numeric zero reaches configuration
validation. The shared setting flags are:
The application configuration scope uses ConfigKit's native effective values,
source evidence, explanation, comparison, and redaction. PromptKit supplies its
own configuration and resource scopes and request preparation, validation, and
explicit smoke diagnostics. Inspection does not require a processing-ready
pipeline or contact a provider. Processing preflight separately checks the selected
profiles and glossary entries. Smoke tests can contact providers and are run
only on explicit request.
| Setting | Flags |
| --- | --- |
| Profile selection | `--proposal-profile`, `--validation-profile` |
| Pipeline and output | `--modules`, `--output-schema` |
| Validation budget | `--validation-max-prompt-tokens` |
| Chunking | `--target-sections`, `--max-section-tokens`, `--min-section-tokens` |
| Normalization (numeric seconds) | `--normalize-max-segment-gap`, `--normalize-ellipsis-gap`, `--normalize-max-segment-duration`, `--normalize-max-segment-tokens` |
| Confidence thresholds | `--glossary-confidence-threshold`, `--homophones-confidence-threshold`, `--spoken-word-confidence-threshold`, `--grammar-confidence-threshold` |
| Context | `--transcript-description` |
| Reporting | `--reporting[=true\|false]`, `--report-dir DIR` |
| Debug | `--debug[=true\|false]`, `--work-dir DIR` |
`process` alone accepts `--glossary` (required) and `--output`.
An omitted or empty output value selects stdout. Nonempty output filenames are
used literally, including whitespace.
Reporting defaults to enabled. `--reporting=false` disables all three ordinary
reports; an explicit false overrides a true file or overlay setting. For stdout
output, reports use the effective `reporting.stdout_dir`, which defaults to the
invocation working directory. For file output, they go beside the transcript
unless `--report-dir` is explicitly supplied. The flag selects the report
directory for either transcript destination; a config-file or overlay value for
`reporting.stdout_dir` alone affects stdout output only. A selected report
directory must be nonblank when reporting is enabled. With reporting disabled,
the report destination is inactive and is not probed. `--debug` separately
enables retained detailed artifacts under `--work-dir`; selecting `--work-dir`
alone does not enable capture. Configuration inspection does not create or
probe these output directories.
Per-role model, base URL, key, timeout, retry, and concurrency flags have been
removed. Models and generation controls belong to PromptKit profiles, backend
credentials and capacity to configuration, and retry/deadline settings to the
shared LLM section. Legacy configuration environment overrides are ignored.
## Streams and exit status
`config validate` loads settings and both selected PromptKit profiles offline,
then prints `config is valid` on success. `config print-effective` accepts
`--view settings|profiles|explain` and defaults to `settings`. Settings writes
ConfigKit's redacted effective-settings YAML. Profiles writes an Audita-owned
YAML summary of selected ID, backend, model, sampling controls, per-attempt
timeout, service tier, and reasoning effort for each role. It omits credentials,
endpoints, and arbitrary extra provider parameters. Explain writes a YAML
sequence of field paths, source origins, and recorded derivations without
resolved setting values. An inherited field may also include an `inheritance`
sequence; each step identifies `from`, `to`, and `reference` paths as JSON
pointers. These fields describe the effective inheritance chain without
including configuration values. A direct child override reports its own source
instead. Debug configuration origins use the same explanation shape. These views
share the same settings and profile validation path as `process`. Unknown views
are usage errors. The effective settings YAML is for inspection and is not
guaranteed reloadable.
For `process`, `--output` writes the corrected transcript to a file and leaves
stdout empty on success. Without it, stdout carries transcript JSON only on
success. Enabled reporting creates `errors.yml`, `recoveries.yml`, and
`report.md` in the selected directory. Successful stderr begins with
`Completed: N corrections applied; E work units with errors; R recoveries.`
Report and debug locations follow only when created. Model-operation failures
can coexist with a completed run and applied corrections; read the YAML reports
for details. Debug artifacts are created only with `--debug`. See the
[report contract](integrations/output-files.md).
Exit codes are `0` for success, `1` for runtime or output failure, and `2` for
usage or configuration input errors. Invalid settings and profiles return `2`;
broken embedded assets, caller cancellation, fatal processing, and required
output failures return `1`. A late report-write failure can follow a published
transcript; exit status and report status remain authoritative.
Configuration commands inspect profiles without contacting a provider.
See the [input files](integrations/transcript-glossary-files.md),
[subprocess contract](integrations/subprocess.md), and
[artifact lifecycle](operations.md) for their respective details.
Process stdout contains transcript JSON when no output file is selected. Ordinary
reports may record recoverable model failures even when processing completes.
Exit status `0` means success, `1` runtime or output failure, `2` invalid usage
or input, and native comparison may return `3` for differences. A missing
processing profile or required glossary selection is an input failure. See the
[output contract](integrations/output-files.md) and [subprocess contract](integrations/subprocess.md).

View File

@@ -1,192 +1,114 @@
# Audita Configuration
This reference describes the version-2 configuration loader in `internal/core/config`.
Use the maintained [local](../examples/minimal-config.yml) and
[service](../examples/production-config.yml) examples with their separately
selected [local profiles](../examples/profiles/local/) and
[service profiles](../examples/profiles/service/), plus the optional
[testing overlay](../examples/overlays/testing.yml).
The [ConfigKit inheritance example](../examples/configkit-inheritance.yml)
shows a local child backend reusing and overriding sibling settings.
Choose real models for your endpoint; a testing profile makes no cost or quality
guarantee. See the [migration guide](migrations/v2.md) for retired inputs.
Audita uses version 3 application configuration. See the [migration guide](migrations/v3.md)
and [examples](../examples/) for complete projects. Command syntax is owned by
[the CLI reference](cli.md).
## Loading and precedence
## Loading and composition
The application selects one main YAML file: an explicit `--config`, then
`/usr/local/etc/audita/config.yml` if present, then `/etc/audita/config.yml`
if present. Missing system candidates are skipped; an explicit missing or empty
path, inaccessible selected file, or absence of any selected file is an error.
`config validate` requires an explicit file. ConfigKit loads built-in defaults,
the selected file, an optional named overlay from `overlays/<name>.yml` beside the
main file, and only explicitly supplied setting overrides, in that order. Imports
and secret-directory bootstrap are disabled. Unknown fields and missing, null,
or non-integer `version: 2` are errors. Version-1 files require migration; no
compatibility loader or implicit environment configuration remains.
An explicit `--config` selects one main YAML file. Without it, ConfigKit searches
the working directory, user configuration directory, and Unix system directories
for `audita` configuration. If no file is found, built-in defaults apply. An
explicit invalid selection or failure of a selected file is an error; search does
not continue after a selected file fails. An omitted version uses the v3 schema;
a supplied version must be `3`.
After overlay and explicit CLI override precedence is applied, ConfigKit resolves
native sibling inheritance before typed decoding. Any input mapping may use
`extends: <sibling-name>`; the child keeps its key, inherits parent settings, and
overrides them with its own settings. Selected overlay and CLI values therefore
participate in inheritance at their normal precedence. The generic syntax and
resolution rules are defined by ConfigKit v0.7.1's
[sibling inheritance contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/docs/config.md#sibling-inheritance).
`extends` is reserved structural input in base files, imports, overlays, and
other application input mappings, including mapping values supplied by explicit
CLI setting overrides. ConfigKit consumes it before typed decoding. A previously
valid backend whose ID is literally `extends` cannot be represented under this
rule. Rename that backend to a non-conflicting ID and update every PromptKit
profile that selects it. This compatibility impact means the upgrade does not
promise that every previously valid configuration remains valid.
Inherited values count as explicit input, including zero, false, empty, and
null. Existing field rules still apply: for example, inherited backend
concurrency must be positive, while an inherited queue capacity of zero is
valid. Parent backends undergo the same decoding and application validation as
other backends, whether or not a selected profile uses them. A child
`credential: null` removes the child's inherited credential; it does not remove
the parent's credential reference, which remains subject to ordinary secret
resolution.
Validation runs after overlays, explicit overrides, and derived settings have
resolved. An override can therefore repair an invalid lower-precedence setting
when that setting can be decoded. ConfigKit retains field origins and derivations
for effective-configuration inspection. Its effective YAML redacts resolved
credentials.
Operator sources may use ConfigKit imports. The selected main file provides the
base for an optional `overlays/<name>.yml`, optional `glossary.yml`, and recursive
`glossary/` YAML files. Without a main source, automatic companion files are not
loaded from the working directory. ConfigKit composes sources, resolves native
inheritance, applies explicit overrides, records derived defaults, and validates
the result. Its [configuration reference](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md)
owns native composition and provenance semantics.
### PromptKit profiles and operator prompts
`profiles_dir` selects a PromptKit configuration root, resolved against the
selected main file's directory unless it is absolute. The root may contain
keyed `profiles`, `backends`, and `prompts` definitions; it is not limited to
profile-only files. IDs come from literal YAML mapping keys, never filenames.
Multiple definitions may share a document, and a document may contribute to any
of the supported mappings. Directory discovery is recursive, but discovery
order does not establish field precedence. Contributions within each source
group must compose without conflicting values.
PromptKit loads its default catalog and Audita's embedded prompts, followed by
optional `prompts.yml` and recursive `prompts/` YAML files beside the application
main. Native imports, resource collections, inheritance, and replacement apply.
Profiles, backends, models, credentials, admission, and provider parameters belong
to PromptKit configuration; see its [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.0/docs/formats.md).
The engine captures its sources for an invocation. Edit files and run a new
invocation to pick up changes. Inspection does not require model credentials.
PromptKit assembles sources in this order: its selected catalogs and owned
defaults, Audita's embedded prompt/schema inputs, operator documents under
`profiles_dir`, then the application backend mapping. The application mapping
owns each configured endpoint, concurrency limit, queue capacity, and credential
environment lookup. Other supported provider fields can be contributed by the
operator documents. Imports remain disabled. The current maintained examples
select separate roots: [local](../examples/profiles/local/) and
[service](../examples/profiles/service/), so definitions for one backend do not
enter the other example's final configuration.
## Pipeline and glossary selections
Both selected roles must resolve to an existing profile, registered backend,
nonblank effective model, and nonblank endpoint. The normalized effective
endpoint must match the application backend endpoint. A selected profile cannot
introduce a competing `api_key_env` lookup; the application backend credential
supplies the runtime key when required. Other unselected profiles may be
partial, but every final backend, profile, and prompt definition is validated
when the engine is constructed. A malformed or conflicting unused definition
can therefore make the selected root invalid. A missing selected root is an
operator configuration error; an empty root may contribute no definitions.
`glossary_collections` maps names to collections with an ordered `entries` list.
Each entry has an `id`, `name`, and `category`; `description`, `aliases`, and
`plural` provide optional context. Entries are identified within their collection
by `id`. Root `glossaries` and `protected_terms` select collection names. If root
protection is omitted, it derives from the root glossary selection.
Profile IDs and parent IDs are exact, literal keys. PromptKit profiles can use
native `extends` inheritance; child fields override inherited fields, while
unmentioned controls survive changes to model or backend. For example:
`pipeline.stages` is an ordered list of `module` records; supported modules are
`glossary`, `homophones`, `spoken_word`, and `grammar`. The default sequence is
`glossary`, `homophones`, `glossary`, `spoken_word`, `grammar`. Repeated modules
run separately; `[]` runs normalization without model processing. An optional
nonempty, unique `id` identifies a record in evidence. Each record may override
`glossaries`, `protected_terms`, and fields under `llm`,
`validation`, and `context`. Omitted fields inherit their resolved root values.
Explicit empty lists and null list selections clear a selection.
```yaml
profiles:
"shared~base":
backend: service
model: example-model
temperature: 0.4
top_p: 0.8
"proposal fast":
extends: "shared~base"
model: faster-model
temperature: 0
```
Each entry receives its selected context and independent protection. Glossary
correction exempts active recognized spellings from protection for that entry.
A longer exempt name still takes precedence over a shorter protected spelling
inside it. A glossary correction must have at least one selected entry at
processing preflight. Empty definitions and empty protection remain valid
configuration.
Presence matters. Explicit `temperature: 0` is sent as zero; omission leaves it
unspecified; null suppresses an inherited temperature. Other fields have their
own native null and omission rules. Provider `extra_params` maps merge
recursively, and a null provider value is sent as JSON null. See the pinned
[PromptKit format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.14.0/docs/formats.md)
for the complete field semantics.
The bundled prompts use English. The modules request complementary work:
Operator documents can also override an embedded prompt/version, including its
messages and definition-level output settings. Shared variables supplied by the
adapter are rendered only when an effective message references them; Audita does
not append omitted shared text. Audita's per-call schemas, structural repair
budget, and downstream domain validators remain in force. The engine captures
effective definitions and message-file contents when constructed, so edits are
observed only by a newly constructed runtime.
- `glossary`: context-supported corrections toward selected glossary terms.
- `homophones`: plausible spoken-word mistranscriptions, including glossary terms.
- `spoken_word`: conservative filler, hesitation, and accidental repetition cleanup.
- `grammar`: punctuation, capitalization, spacing, and whole-word `a`/`an` cleanup.
### Migrating PromptKit profile documents
For the PromptKit v0.11 format, wrap each profile's fields under
`profiles: {<literal-id>: ...}`, remove inner `id`, and replace
`base_profile` with `extends`. Profile and prompt IDs are mapping keys, so they
need not match source filenames. Review zeros, omitted values, and nulls against
the native presence rules before deploying. Select a root whose final
definitions have valid backend references; eager validation applies even to
unselected definitions. See the complete maintained [local](../examples/minimal-config.yml)
and [service](../examples/production-config.yml) examples and the pinned
[consumer migration guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.14.0/docs/consumers/pkg-promptkit.md#migrate-from-the-previous-configuration-api).
This incompatible profile-format migration is intended for an Audita major
release; no automatic file conversion is provided.
The [CLI inspection views](cli.md#streams-and-exit-status) show selected
controls and field provenance separately from ConfigKit's redacted settings
YAML. Inspection resolves both roles without provider calls.
Otherwise acceptable minor editorial cleanup may be accepted across modules, as
specified by the [editorial acceptance boundary](policy/architecture.md#correction-and-concurrency-invariants).
## Settings
| Field | Default | Rule |
| Setting | Default | Meaning |
| --- | --- | --- |
| `profiles_dir` | `profiles` | Nonempty PromptKit document root; resolved relative to the selected main file, or absolute. |
| `backends.<id>.endpoint` | None | Required nonempty endpoint for each backend. At least one backend is required. |
| `backends.<id>.concurrency` | `1` | Positive finite capacity; shared by both roles using that backend. |
| `backends.<id>.queue_capacity` | `1024` | Nonnegative; zero disables waiting admission. |
| `backends.<id>.credential` | Unset | Optional environment-variable secret reference; omission or null means unauthenticated use. |
| `llm.proposal_profile` | None | Required nonempty profile ID. |
| `llm.validation_profile` | Final proposal profile | Omission inherits the final proposal selection; explicit empty or null fails. |
| `llm.transient_retries` | `2` | Nonnegative additional attempts per generation. |
| `llm.repair_attempts` | `2` | Additional structural repair generations, from zero through three. |
| `llm.operation_timeout` | `15m` | Positive Go duration string per logical call. |
| `pipeline.modules` | `[glossary, homophones, glossary, spoken_word, grammar]` | Ordered module keys; repeats are meaningful and an explicit empty list runs no correction modules. |
| `output.schema` | `bare-segments` | `bare-segments` or `audita-v1`. See [output formats](integrations/output-files.md). |
| `llm.proposal_profile` | unset | PromptKit profile for proposals; required for processing entries. |
| `llm.validation_profile` | effective proposal profile | Profile for model validation; null clears a selection before fallback. |
| `llm.correction_repair_profile` | effective proposal profile | Profile for correction repair; null clears an inherited selection before fallback. |
| `llm.correction_repair_attempts` | `1` | Nonnegative repair attempts per correction; zero disables correction repair. |
| `llm.transient_retries` | `2` | Additional transient attempts per generation. |
| `llm.repair_attempts` | `2` | Structural repairs, from zero through three. |
| `llm.operation_timeout` | `15m` | Positive duration per logical operation. |
| `validation.max_prompt_tokens` | `2048` | Positive validation batching budget. |
| `chunking.target_sections` | Unset | Optional positive target; omission or null selects automatic chunking. |
| `chunking.max_section_tokens` | `8192` | Positive maximum estimate. |
| `chunking.min_section_tokens` | `2048` | Positive and no greater than maximum. |
| `normalization.max_segment_gap` | `4.0` | Nonnegative numeric seconds. |
| `normalization.ellipsis_gap` | `3.5` | Nonnegative numeric seconds. |
| `normalization.max_segment_duration` | `60.0` | Positive numeric seconds. |
| `normalization.max_segment_tokens` | `2048` | Positive token estimate. |
| `thresholds.glossary`, `.homophones`, `.spoken_word`, `.grammar` | `0.8` each | Confidence thresholds in `[0, 1]`. |
| `context.description` | Empty | Trimmed prompt context, at most 500 bytes. |
| `reporting.enabled` | `true` | Write the ordinary three-file report bundle when processing. |
| `reporting.stdout_dir` | `.` | Report directory for stdout transcript output; a `--report-dir` flag can select reports for either transcript destination. |
| `diagnostics.debug` | `false` | Persist detailed debug artifacts when processing. |
| `diagnostics.work_dir` | `/tmp/audita` | Parent of the retained debug run directory; required only when debug is enabled. |
| `context.description` | empty | Prompt context; at most 500 bytes after trimming. |
| `chunking.target_sections` | unset | Optional positive count. Processing requires exactly this many nonempty sections when specified. An infeasible count is an input error. |
| `chunking.max_section_tokens`, `chunking.min_section_tokens` | `8192`, `2048` | The maximum bounds a section's estimated tokens, except for an oversized segment in a section of its own. The minimum is validated against the maximum and retained for compatibility. |
| `normalization.max_segment_gap`, `normalization.ellipsis_gap` | `4`, `3.5` | Nonnegative seconds. |
| `normalization.max_segment_duration`, `normalization.max_segment_tokens` | `60`, `2048` | Positive seconds and token estimate. |
| `output.schema` | `bare-segments` | Output format; see [output contracts](integrations/output-files.md). |
| `reporting.enabled`, `reporting.stdout_dir` | `true`, `.` | Ordinary report capture and default directory for stdout output. |
| `diagnostics.work_dir` | `/tmp/audita` | Parent directory for optional debug capture. |
Module keys select correction modules; validator chains remain built into them.
The loader preserves module order and repetitions. Normalization time settings
accept numeric seconds only. The operation timeout uses a duration string.
`reporting.stdout_dir` must be nonblank when it supplies the active report
destination: for stdout output, or for file output when `--report-dir` is
explicitly supplied. File output without that flag uses the transcript's parent,
so the configured value is inactive. Reporting-disabled runs do not select a
report directory. `diagnostics.work_dir` must be nonblank only with debug
enabled. These path requirements are checked when choosing process destinations,
not during configuration inspection.
For example, an entry can disable correction repair or select another profile:
## Credentials
```yaml
llm:
proposal_profile: local
correction_repair_attempts: 2
pipeline:
stages:
- module: grammar
llm:
correction_repair_profile: review
- module: spoken_word
llm:
correction_repair_attempts: 0
```
A backend credential is a ConfigKit secret reference containing an environment
variable name, such as `credential: AUDITA_SERVICE_KEY`. Every reference that
survives overlay and override resolution must name a set, nonempty variable,
including credentials on backends unused by the selected roles. A replacement
reference resolves only the replacement; null removes the reference. General
`AUDITA_*` and `OPENROUTER_API_KEY` variables have no implicit setting effect.
Secret values are available to the runtime through the resolved reference, while
ConfigKit's effective output and provenance contain no resolved secret values.
Current invocation syntax belongs in [CLI](cli.md).
Processing profiles are selected explicitly; no profile or glossary is selected
automatically. The validation selection falls back after root and per-entry
settings are combined. An explicit root correction repair profile is inherited
by each entry unless overridden or cleared with null; otherwise the entry uses
its effective proposal profile. The repair profile is checked only when its
attempt budget is positive. Each correction repair attempt is a logical call
that can also use the configured transient retries and structural repairs. Null
does not disable validation. Numeric zero and false
retain their field meaning, subject to validation. Inspect recorded origins and
default dependencies using the [native commands](cli.md).

View File

@@ -41,7 +41,7 @@ ownership. Commit discipline and agent Git restrictions are in the
## Baseline Validation
Use Go 1.26.0 or newer for source builds. The selected release toolchain is
Use Go 1.27.0 or newer for source builds. The selected release toolchain is
documented in the [release procedure](release.md#prerequisites). From the
repository root:

View File

@@ -1,26 +1,26 @@
# OpenAI-Compatible LLM Integration
Audita uses the pinned [PromptKit](https://gitea.maximumdirect.net/eric/promptkit)
Audita uses the pinned [PromptKit](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/171fb11f4e967a1da3af57843c6467954b14ba09)
built-in OpenAI-compatible transport. PromptKit owns chat-completions wire framing,
provider envelope parsing, transient retries, per-generation timeouts, and JSON
Schema repair. A backend's configured base endpoint must support the selected
profile's model and structured JSON-schema responses; local configuration
inspection does not contact the provider.
Audita selects a role profile, supplies its registered backend credential, and
passes the embedded response schema as a complete per-call output contract. It
prepares each call once, checks that the prepared target still matches the
inspected backend and endpoint, then executes that same prepared request. A
profile cannot introduce a separate credential environment lookup. An absent
backend credential permits an unauthenticated local service.
Audita selects role profiles independently for each pipeline entry and supplies
its domain response schema and per-operation budget. PromptKit owns backend and
credential selection, request preparation, transport, retries, repairs, and
admission. Audita executes the same prepared handle and retains its own domain
validation. Profiles may use native endpoint and credential settings; local
inspection does not resolve a credential value or call the provider.
`llm.transient_retries` counts additional attempts for eligible transient
failures; explicit zero makes one attempt. `llm.repair_attempts` counts
additional generations for schema-invalid model output. The operation timeout
covers preparation, capacity waiting, retries, generation, and repair. Caller
cancellation or an earlier deadline also applies. See [configuration](../config.md#settings)
for defaults and [PromptKit v0.14.0's consumer contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.14.0/docs/consumers/pkg-promptkit.md)
for the pinned protocol and retry details.
for defaults and the [PromptKit consumer contract](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.0/docs/consumers/pkg-promptkit.md)
for protocol and retry details.
A model operation that exhausts structural repair, a live-parent local operation
timeout, capacity rejection, transport failure, malformed provider response,
@@ -31,4 +31,4 @@ continue. Caller cancellation, broken assets or configuration, and unknown
internal failures remain fatal and cancel peers. Audita decodes into domain
types only after PromptKit validates the JSON. Ordinary reports use safe reason
codes and counts rather than provider messages. Full request/response content
is written only with `--debug`; see [operations](../operations.md#diagnostics-directory).
is written only with `--debug`; see [operations](../operations.md#debug-evidence).

View File

@@ -5,7 +5,7 @@
The corrected transcript uses the selected `output.schema`: `bare-segments`
or `audita-v1`. Its schema and text rules are unchanged by resilience
reporting. See [configuration](../config.md#settings) for selection and
[operations](../operations.md#required-output-files) for placement and writes.
[operations](../operations.md#outputs-and-lifecycle) for placement and writes.
With reporting enabled, Audita produces three ordinary files:
@@ -46,24 +46,34 @@ remain in opt-in debug files.
## Error and Recovery Records
An `errors` record with `scope: work_unit` identifies zero-based `stage_index`
and `chunk_index`, module key/instance, initial segment range, applied-correction
and `chunk_index`, optional `stage_id`, module key/instance, initial segment range, applied-correction
count, and a `failures` sequence. Each failure identifies the operation
(`proposal`, `validation`, or `validation_input`), optional validator and
(`proposal`, `validation`, `validation_input`, or `correction_repair`), optional validator and
zero-based batch index, safe reason/message, sorted proposal indices when
known, and execution counts when available. Multiple failed batches in one
work unit form one error record. `scope: run` instead records phase, safe reason
and message, optional origin, and output path where relevant. It can describe
a fatal error or secondary output-write failure without inventing a failed
model work unit. Raw provider errors and transcript text are absent.
work unit form one error record. A record with scope `run` records a fatal
processing failure or a separate output delivery failure. It identifies the
phase, safe reason and message, and available origin. A processing origin can
include the operation, validator, batch, proposal index, and repair attempt.
A delivery failure includes the output path when known. The initiating
processing failure can include an `interruptions` sequence with each
available peer's phase, safe reason and message, and available origin.
Peer details do not add to the recoverable work-unit or run-error counts.
The work-unit matrix marks interrupted work. Raw provider errors and
transcript text are absent.
For `validation_decisions_invalid`, proposal indices identify only candidates
whose required decisions were unavailable. Other candidates in the same batch
may still be approved or rejected normally.
Each recovery identifies its work unit and successful operation, with sorted
Each recovery identifies its work unit, optional `stage_id`, and successful operation, with sorted
`reasons`, a safe message, available execution counts, and sorted
`filtered_proposals` details. One recovery can contain `output_repaired`,
`service_recovered`, and `proposals_filtered` together. Filtering covers
defective response proposals; low confidence, protected-term rejection,
`service_recovered`, `correction_revised`, and `proposals_filtered` together.
`correction_revised` means a repair yielded a fully validated revision; its
application outcome is recorded in the Markdown report. Filtering covers
defective proposals and revisions under their originating operation. Only
original proposal operations count toward `proposal_responses_with_filtering`.
Protected-term rejection,
ordinary editorial rejection, and an apply-time conflict caused by an earlier
accepted correction are not filtering recoveries. Failed operations are errors,
not recoveries. The initial chunk identity remains stable even if earlier
@@ -79,23 +89,29 @@ is an error even when unexpected indices were also ignored.
`report.md` includes run ID, status, corrections, work coverage, error and
recovery totals, input/output paths, and full work-unit error and recovery
matrices. Rows show every initial chunk with 1-based chunk number and initial
segment range; columns follow configured module-instance order, including
repeats. Completed error cells are `0` or `1`; recovery cells are operation
segment range; columns follow configured pipeline order, including repeated modules. Labels show
the one-based position and module, plus the operator ID when supplied. Completed error cells are `0` or `1`; recovery cells are operation
counts. `—` means not started and `n*` means interrupted with n facts recorded.
An empty stage or chunk set is identified as having no work units. Short reason breakdowns count
records containing each reason; a recovery can have several reasons, so those
counts need not sum to the recovery total. The report refers to both YAML
files. It does not include transcript excerpts or correction lists.
counts need not sum to the recovery total. When a repair was attempted, a
Correction repair table lists its stage, chunk,
original proposal index, semantic attempt count, and final outcome (`applied`,
`approved_skipped`, `withdrawn`, `rejected`, `exhausted`, `unavailable`, or
`interrupted`). The report refers to both YAML files. It does not include
transcript excerpts or correction lists.
## Debug-Only Files
With `--debug`, `correction-ledger.json` contains proposed candidates and
their application, rejection, or interruption details. `llm-execution.json`
holds logical calls and PromptKit execution events; `utilization-diagnostics.json`
groups backend capacity and timing observations while preserving known and
complete usage semantics. Interaction request/response artifacts, selected
profiles, configuration provenance, and input snapshots are also debug-only.
holds logical calls and PromptKit execution events. Interaction request/response
artifacts and input snapshots are also debug-only. Records carry zero-based
`stage_index` and optional `stage_id` where an entry is identified.
These files are diagnostic evidence, not an alternate ordinary report schema.
For a repaired proposal, one ledger row preserves the original proposed edit,
the final applied segment and span when applicable, and repair attempts with
revision decisions and interaction artifact paths.
Each candidate-backed ledger entry includes `proposed_corrected_text`, the
literal replacement span, even when it is `""` for a deletion. Applied entries
also include `applied_corrected_text`, likewise `""` for an applied deletion.

View File

@@ -6,39 +6,51 @@ The [CLI reference](../cli.md) owns command syntax, streams, and exit semantics;
## Invocation
Use an argument array with the transcript path and required glossary argument,
following the [process examples](../cli.md#commands-and-help). For machine workflows,
Use an argument array with the transcript path and configured glossary selections,
following the [process examples](../cli.md#processing). For machine workflows,
select an explicit transcript file destination and a configuration path. Reports
go beside the transcript unless an explicit `--report-dir` selects another
directory. For stdout output, reports use the effective `reporting.stdout_dir`
(defaulting to the invocation working directory), including a `--report-dir`
override. A config-file or overlay value for `reporting.stdout_dir` alone does
not redirect file-output reports. `--work-dir` selects a debug root, while
configuration or `--debug` enables capture; the path flag alone does not.
`--debug` enables capture; the path flag alone does not.
Supplying a configuration path also makes file selection predictable; only
explicitly referenced credential variables are read from the environment.
Choose a trusted configuration bundle. An explicit main path still allows
its configured imports and automatic overlay, glossary, and prompt companions.
Without a main path, Audita uses the configured discovery locations. The
parent controls who can write those sources and which report destinations and
retained debug directories the invocation will use. Native inspection is
separate from processing preflight.
Resolve the executable deliberately and set the child's working directory so
relative input/output paths and reported artifact paths have a known base.
Read stdout and stderr concurrently to avoid pipe blocking, and impose timeout
or cancellation in the parent process when needed.
or cancellation in the parent process when needed. Optional `--progress`
messages arrive on stderr during stage and chunk execution, including model
operations and completions. Debug enables progress by default, and
`--progress=false` or quiet mode suppresses it. Consume progress as
human-readable telemetry. Stdout remains the transcript stream.
## Result Handling
Interpret the exit result according to the
[CLI output and exit contract](../cli.md#streams-and-exit-status).
[CLI output and exit contract](../cli.md#inspection-and-outcomes).
Consume transcript/report data through the
[output-file contract](output-files.md), and treat stderr as human-readable detail.
The three reports may be absent after early configuration or destination
failures. After initialization, failed reports can describe invalid input or
partial processing and use the same selected report directory as successful
runs. Exit `0` can include recoverable model errors and applied
Audita loads configuration and parses the input transcript before report
initialization. Early destination failures can also leave no reports. After
initialization, failed reports can describe partial processing or output
failures and use the same report directory as successful runs.
Exit `0` can include recoverable model errors and applied
corrections; inspect `errors.yml` and `recoveries.yml` for those outcomes. A
transcript may have been written before a later required report failure, so
the file alone does not prove completion.
If processing fails, preserve available evidence and follow
[operations recovery](../operations.md#failure-inspection-and-recovery).
[operations recovery](../operations.md#recovery).
Ordinary reports are independent of optional retained debug evidence. Parent
cancellation reaches the child through its context; Audita joins workers and
attempts failed-status report finalization before exiting. Uncatchable
@@ -49,4 +61,4 @@ file nor a debug directory alone establishes successful completion.
- [Transcript and glossary inputs](transcript-glossary-files.md)
- [LLM endpoint compatibility](openai-compatible-llm.md)
- [Configuration inspection commands](../cli.md#commands-and-help)
- [Configuration inspection commands](../cli.md#inspection-and-outcomes)

View File

@@ -13,7 +13,7 @@ schema/version marker.
| Segment field | Type and validation |
| --- | --- |
| `id` | Optional integer (or null). Supplied IDs must be unique; missing IDs are accepted. |
| `id` | Optional integer (or null) in the Go `int` range for the executable's architecture. Supplied IDs are compared exactly and must be unique. |
| `speaker` | Non-empty string |
| `start`, `end` | Numeric seconds, finite and non-negative; end must be at least start |
| `text` | Non-empty string |
@@ -21,30 +21,18 @@ schema/version marker.
Supply explicit start and end times for meaningful timing. The current decoder
uses zero for missing or null timestamps rather than enforcing their presence.
String validation checks empty values, not whitespace trimming. Normalization can
merge segments and reassign IDs, so source IDs need not match output IDs.
String validation checks for empty values. Normalization can merge segments and
reassign IDs, so source IDs need not match output IDs.
The [tiny transcript](../../examples/tiny-transcript.json) is a complete copyable
input. Invalid JSON, unsupported top-level shapes, empty transcripts, invalid field
types, duplicate supplied IDs, and the validation failures above are rejected.
## Glossary YAML Contract
## Glossary collections
The top-level object contains a `glossary` list with at least one entry.
| Entry field | Type and validation |
| --- | --- |
| `name` | Non-empty string |
| `category` | Non-empty string |
| `summary` | Non-empty string |
| `aliases` | Optional list of non-empty strings |
| `plural` | Optional string |
The parser checks empty strings without trimming them. Unknown YAML fields are
ignored by the glossary parser, unlike the stricter
[configuration-file schema](../config.md#loading-and-precedence).
The [tiny glossary](../../examples/tiny-glossary.yaml) is a complete copyable input.
Malformed YAML, an empty/missing glossary, invalid shapes, missing required text,
and empty aliases are rejected. These formats describe input acceptance, not
additional vocabulary restrictions.
Glossary definitions are composed as application configuration, including the
optional companion inputs described by the [configuration reference](../config.md).
The [local example](../../examples/local/glossary.yml) provides a complete
collection. Configuration may contain empty collections; processing preflight
requires every glossary-correction entry to select at least one glossary entry.
The previous standalone `glossary` file format is not a processing input.

View File

@@ -9,13 +9,12 @@ CLI wiring, and maintained examples. Definitions of behavior belong to the
1. Update fields, defaults, loading, and validation in `internal/core/config`.
2. Update file, selected overlay, credential reference, and CLI mapping as
applicable. Preserve the precedence defined in the
[configuration contract](../config.md#loading-and-precedence), including the
[configuration contract](../config.md#loading-and-composition), including the
distinct validation and effective-config commands.
3. Update redaction when secrets are involved.
4. Review configuration tests and related CLI tests for precedence, validation,
3. Review configuration tests and related CLI tests for precedence, validation,
and source-specific behavior. Add or adjust tests for the changed contract
according to the [testing policy](../policy/testing.md).
5. Update the configuration reference and affected [examples](../../examples/).
4. Update the configuration reference and affected [examples](../../examples/).
## Changing CLI Behavior
@@ -29,33 +28,25 @@ CLI wiring, and maintained examples. Definitions of behavior belong to the
The `version` route uses ReleaseKit's public `buildinfo.Version()` accessor and
stays independent of application runtime assembly. Preserve its behavior from
the [CLI contract](../cli.md#commands-and-help) when changing the command; the
the [CLI contract](../cli.md) when changing the command; the
adoption decision is recorded in [ADR 0001](../adr/0001-releasekit.md).
Processing preflight checks glossary selections before inspecting proposal,
validation, and enabled repair profiles in pipeline order. The checked plan
carries the resolved module specs and glossary views into execution. It reuses
profile and backend inspections and equivalent glossary views within the
invocation. Native inspection commands continue to inspect configuration
without running processing readiness checks.
## Validating Examples
Keep complete copyable files in [examples](../../examples/) and link to them from
their canonical contract documentation. Keep them valid and secret-free.
From the repository root, validate the maintained configuration examples:
```sh
go run ./cmd/audita config validate --config examples/minimal-config.yml
go run ./cmd/audita config validate --config examples/configkit-inheritance.yml
AUDITA_SERVICE_KEY=synthetic-example go run ./cmd/audita config validate --config examples/production-config.yml
AUDITA_SERVICE_KEY=synthetic-example go run ./cmd/audita config validate --config examples/production-config.yml --overlay testing
go run ./cmd/audita config print-effective --config examples/minimal-config.yml --view profiles
go run ./cmd/audita config print-effective --config examples/configkit-inheritance.yml --view explain
```
The local and ConfigKit inheritance files select `profiles/local`; the service
file selects `profiles/service`, including the service testing profiles. Keep
these roots separate because PromptKit validates every final definition in a
selected root, including definitions that are not selected for a role.
Only referenced credentials read environment values; use a controlled synthetic
value when validating the service example. Check affected CLI examples against the
parser and use schema tests for maintained transcript/glossary inputs. Example
validation should not invoke a live LLM merely to check documentation.
Run the commands in the [example guide](../../examples/README.md) from each
project's directory. `internal/cli/examples_integration_test.go` exercises the
maintained projects with a controlled provider, and the preview fixture can be
prepared without inference. Review automatic companion sources and overlays in
their actual project directories. Keep service credentials synthetic in tests.
## Runtime Change Checks
@@ -66,8 +57,7 @@ Select checks according to the [testing policy](../policy/testing.md):
- Process/output changes: verify stdout, stderr, exit, output-file, and report
behavior against the [CLI contract](../cli.md) and
[subprocess guidance](../integrations/subprocess.md), including failures.
- Report or diagnostics changes: review [report assembly tests and redaction
checks](diagnostics-reporting.md#key-tests), metadata fields, and artifact paths.
- Report or diagnostics changes: review [report assembly tests](diagnostics-reporting.md#key-tests), metadata fields, and artifact paths.
- Schema or serialization changes: review [output-schema tests](output-schemas.md#key-tests)
and `internal/core/schema` tests, including supported formats and rejection of
unsupported schemas.

View File

@@ -12,8 +12,7 @@ work-unit errors, separate run errors, and one recovery per successful logical
operation. Reports order stages, sections, validators, and batches by semantic
identity, never concurrent completion time. The core reporting package owns
Audita's versioned YAML DTOs, fixed Markdown rendering, and brief CLI
completion formatter. YAML redaction walks serialized string nodes so numeric
and boolean values retain their types. Ordinary reports omit raw causes,
completion formatter. Reports encode the typed documents directly to YAML. Ordinary reports omit raw causes,
transcript text, complete decisions, and token/timing payloads.
Validation operations with unavailable decisions report only affected requested
indices, even when other candidates in the batch continue. Ignored extra
@@ -21,39 +20,53 @@ validator entries yield `validation_decisions_filtered` only for a successful
operation; they do not count as filtered correction proposals. Failed operations
retain their execution counts and never produce a recovery record.
`internal/core/diagnostics.OutputSession` owns active destination checks,
transcript preflight, report initialization, regular-file replacement, and direct
stream publication. Transcript input is protected from early report writes but
may be the final transcript destination. The LLM runtime records successful reads
through PromptKit's profile filesystem and supplies those source paths to CLI;
`internal/core/diagnostics.OutputSession` owns destination selection, report
initialization, and publication. Transcript and report files share a staging
primitive that writes beside the resolved destination. Streams are opened for
delivery. Transcript input is protected from early report writes but
may be the final transcript destination. The LLM runtime records consumed PromptKit sources and effective host message
files and supplies those source paths to CLI;
no second filename-based discovery rule is used.
CLI composes it after configuration/profile inspection and before reading
inputs or dispatching model work. It does not create ordinary report parents.
On a final write error it attempts other enabled reports and one failed-status
pass; a published transcript is never erased by a later report failure.
CLI composes it after configuration, transcript acquisition, and preflight
readiness and before dispatching model work. It does not create ordinary report parents.
Final report rendering includes delivery and cleanup errors observed so far.
When another failure becomes known, later writes use updated failed reports.
One best-effort pass refreshes earlier reports with stale evidence. A published
transcript remains available after a later report failure.
Debug is independent. Only `diagnostics.debug` creates a unique retained child
under `diagnostics.work_dir`. CLI passes empty diagnostics paths and nil writers
when debug is off. With debug on, source/normalized snapshots, invocation,
effective settings, origins, profiles, initial chunk summary, correction ledger,
indexed execution/utilization, and model interactions are written. Runner
candidate capture includes proposals later rejected or interrupted. Ledger
mapping uses optional string pointers so an empty proposed replacement is
serialized for every candidate and an empty applied replacement appears only
when that candidate applied; see the [public artifact contract](../integrations/output-files.md#debug-only-files).
Debug write failures reach the CLI through an explicit concurrency-safe diagnostic
callback and produce redacted stderr messages without aborting processing.
Completed validator decisions returned with a fatal batch error remain available
to the debug ledger; they never authorize applying an incompletely validated edit.
Runner decision records carry the validator's explicit approved, rejected, or
unavailable disposition into the ledger. Unavailable candidates have a distinct
top-level ledger disposition, while fatal interruptions remain interrupted when
no rejection or unavailable decision was returned. Successful validation
interaction payloads contain the full decoded response, final content, and
reconciliation outcomes; ignored indices do not become ledger candidates.
Every debug writer uses all configured backend secrets for redaction, including
unselected backend credentials and source snapshots. Debug can still contain
sensitive transcript and prompt content.
Debug is independent. The shared `--debug` flag enables a unique retained child
under `diagnostics.work_dir`. The CLI creates one interaction sink rooted in
that directory and passes it to proposal generation, validation, and repair.
With debug enabled, it saves the source bytes as acquired, separate from the parsed and normalized
transcript snapshots. It also captures invocation metadata, effective settings
rendered by ConfigKit, the correction ledger, LLM execution observations, and
model interactions. Candidate capture includes proposals later
rejected or interrupted. Repair and revalidation artifacts use section, proposal,
attempt, validator, and batch coordinates as applicable. Request metadata records
these coordinates with the interaction role. Proposal request metadata carries
the zero-based response origin (`start_index`) and the ordered `segment_ids`
used to interpret response references. Each interaction retains its available
prepared request, response, and failure evidence. Ledger mapping preserves empty
proposed and applied replacements and distinguishes unavailable candidates from
interrupted work.
While final proposal indices are pending, repair request snapshots share their
unchanged message prefix. Each written request contains its full history.
The sink groups concurrent write failures by role, artifact operation, and cause.
Warnings report the count and an affected path. The writer still attempts other
artifacts and returns the paths it wrote, and the CLI presents warnings separately
from processing outcomes and required delivery. Debug artifacts can contain sensitive transcript and
prompt content. Execution
position and optional operator ID are carried separately from generated safe
artifact path coordinates.
Execution diagnostics include a native-group invocation summary and per-call
summaries. Terminal coverage is separate from usage completeness; unknown usage
is distinct from known zero. Overlapping summaries must not be added together.
The collector snapshots after work joins and retains domain labels and stable
presentation order. Prepared evidence comes from `OnPrepared`, so preparation or
admission failures may have no request snapshot. Coordinator execution failures
still finalize the attempted logical call and its available evidence.
## Key Tests
@@ -61,3 +74,17 @@ Useful tests: `internal/core/reporting/*_test.go`,
`internal/core/diagnostics/*_test.go`,
`internal/framework/processreport/*_test.go`, and
`cmd/audita/main_integration_test.go`.
Report projection uses typed operation and delivery results. Recoverable
operations count toward work-unit errors. A fatal processing cause retains its
own phase and available operation coordinates, and peer interruptions and later
file failures preserve their own attribution. The correction ledger joins one
candidate row by module instance and proposal index, preserving repair lineage
and the recorded validator execution class.
The invocation selects retained evidence once. Summary-only processing
accumulates counters as completed sections leave the work window. Ordinary
reports retain the full work matrix and the operation facts that contribute to
errors and recoveries. Debug retains
candidate and decision history, repair lineage, and native observations.
Without debug, the runtime skips prepared message snapshots.

View File

@@ -1,60 +1,66 @@
# Audita LLM Runtime
## Client Boundary
`llm.NewRuntime` assembles one captured PromptKit engine using its default
catalog, Audita's embedded prompts and schemas, and optional operator sources
anchored to the recorded application main context. Captured host sources and
message files are passed to output collision checks. An embedded-only diagnostic
construction distinguishes shipped asset failures from operator-source failures;
it never replaces the requested engine.
`llm.NewRuntime` assembles one PromptKit engine for both roles. PromptKit's
catalogs and defaults are followed by Audita's embedded prompt and schema
inputs, operator documents from `profiles_dir`, and the highest-priority
application backend mapping. Audita owns backend endpoints, capacity settings,
and resolved credentials; native PromptKit layering owns profile inheritance,
prompt overrides, and provider-specific fields. Imports are disabled. The
runtime inspects both selected roles offline, requiring complete model and
endpoint values and rejecting competing profile credential lookups. A
role-bound `llm.RoleClient` implements `structuredoutput.Client`; proposal and
validator contracts alias that interface. Both roles share engine-local backend
capacity.
Each resolved pipeline entry receives role-bound clients with its selected
profiles and effective budgets. Clients share engine-local backend admission.
The adapter uses ordinary `Run` with `OperationTimeout` and `OnPrepared`, passes
Audita's per-call schema and repair budget, and decodes only validated results.
The operation budget includes preparation, admission, retries, and structural
repair. An expired parent context stops processing and retains any native cause.
With an active parent, PromptKit's operation deadline remains recoverable even
when a preparation error wraps it. A native transport timeout affects the HTTP
attempt and is recorded as a transport failure. The prepared notification
supplies prompt metadata to observers. With debug capture enabled, it also
supplies the actual request messages when preparation reaches that point.
PromptKit owns backend and credential selection. When a required credential is absent,
the CLI identifies the role, profile, and environment variable using the native
diagnostic. See the [integration contract](../integrations/openai-compatible-llm.md)
for failure behavior and the [configuration reference](../config.md) for sources.
Successful construction captures the final definitions and referenced message
contents. The runtime does not reload operator documents or message files during
calls. If final engine construction fails, an embedded-only diagnostic
construction distinguishes shipped asset failures from invalid operator input.
An asset failure remains an asset error; when embedded construction succeeds,
the original failure remains a configuration error. The diagnostic engine
never replaces or executes the requested configuration, and caller cancellation
skips this path. The captured inspection also supplies an internal source
ledger: all loaded host YAML plus effective, source-relative host
`content_file` resources are tracked for output-collision checks.
When correction repair is enabled, the runner checks the module's repair prompt
and coordinator before submitting proposal work. The proposal call captures a
native immutable PromptKit exchange. Each actionable correction starts an independent
`Engine.Coordinate` branch from that exchange. PromptKit assembles continuation
history, owns the additional-turn budget, and delivers the last permitted response
for assessment. Follow-ups select the repair prompt, profile, and output schema
directly; Audita does not rerender the original proposal or assemble replay messages.
An opaque exchange in the structured-output contract keeps provider state outside
modules and validators. The adapter shares request construction, notifications,
observers, and once-only completion between ordinary and coordinated calls.
Completion attaches terminal counts when available and records one logical finish.
Progress uses the adapter's logical call boundaries. Writes to the diagnostic
stream occur outside PromptKit's operation deadline.
Prepared requests and terminal output travel in the returned response for an
optional interaction artifact. Logical call notifications carry metadata.
For each logical call, the adapter starts an operation context and a diagnostic
record before preparation. It supplies the reserved hardening text, the selected
profile and resolved backend credential, and the complete embedded schema/repair
contract. `PrepareExecution` produces the exact messages and hashes retained in
an Audita snapshot. The adapter checks the prepared backend and endpoint before
`RunPrepared`. It records available final content, usage, model, and profile
metadata and decodes only a validated result. Call hooks expose logical
start/finish records and PromptKit execution events for debug utilization.
Audita owns actionable rejection, revision decoding, withdrawal, current previews,
and full revalidation. Each branch returns its attempt facts and final approval
to the section runner. Accepted siblings remain independent. Requesting more work
at the budget boundary produces exhaustion without allocating another logical call.
A canceled, undelivered response supplies diagnostic evidence only; it cannot enter
the approved set. Repair disabled in configuration bypasses coordination entirely.
The runner supplements each repair instruction with its current proposal preview
as described in the [module guide](modules.md#failure-and-outcome-behavior).
The bundled prompts separate durable system principles from the initial user
assignment so later repair instructions can allow acceptable minor cleanup;
see [prompt instruction ownership](prompts.md).
The [integration contract](../integrations/openai-compatible-llm.md) describes
wire ownership and failure behavior. `structuredoutput.Failure` has a safe
message, fixed reason code, typed cause, and recoverable/fatal/canceled class.
Counts distinguish provider attempts, transient retries, and structural
repairs, including on errors. Secrets from all configured backends, including unselected
ones, are available to the diagnostics redaction boundary.
The observation collector tracks logical calls and execution events, and enrolls
selected runs in a native `ExecutionGroup`. Proposal, repair, and nested validator
clients explicitly share the invocation observer; history reuse adds no extra run.
Native summaries deduplicate terminal totals by run ID and retain terminal coverage
separately from usage presence and completeness. Logical calls and run membership
can differ, especially on failures before execution.
CLI explain output and debug configuration origins share a value-free projection
of effective field origins. The [CLI contract](../cli.md) defines its optional
inheritance evidence fields.
## Orchestration
CLI processing supplies two role clients from the same engine to the runner.
PromptKit's per-backend admission applies to both roles and every generation,
retry, and repair. The runner still processes module instances in order,
collects concurrent section work deterministically, and cancels remaining
section work only on fatal failures. `llm.DiagnosticsWriter` remains the protected
request/response artifact writer. `llm.ObservationCollector` captures metadata
events under a short mutex and freezes them after runner work joins. Its logical
records include preparation failures; summary usage comes from terminal events
once per call and retains knownness and completeness for each field. Runner wall
and validator timings remain separate from provider attempts. Ordinary reports
derive compact runner outcomes; full observations are debug-only.
Processing operations retain the failure class, reason, and underlying error.
When a client omits the reason, the operation uses `internal_failure` and keeps
the original class and error chain. Ordinary reports use compact outcomes.
Request and response evidence is optional debug material. The runner preserves
ordered pipeline traversal and deterministic section collection while canceling
and joining peers on fatal errors.

View File

@@ -13,7 +13,13 @@ Modules implement `contracts.TranscriptModule`:
- `Validators()`
- `Propose(ctx, req)`
Runner resolves configured module specs to module instances through `internal/framework/modules`.
Built-in modules also expose `RepairPromptID()` for the runner to select their
repair definitions; proposal-only callers retain the existing interface.
The CLI supplies the built-in factory from `internal/modules` to the runner.
The runner resolves checked module specs through that factory. Module instances
can receive concurrent proposal calls across sections. Request inputs are
borrowed for the call and must be copied before modification or retention.
## Built-In Modules
@@ -37,13 +43,13 @@ Shared proposal-generation plumbing is centralized in:
Module packages own:
- prompt selection (`internal/prompts` prompt IDs).
`proposal_generation.BuildProposalVariables` encodes the glossary, selected
transcript section, and trimmed description once for all four modules. PromptKit
renders their embedded definitions from those variables and validates the
Each stage prepares the encoded glossary context and protected spellings once.
Proposal generation adds the selected transcript section and trimmed description
for each request. PromptKit renders the selected definition and validates the
correction-set schema before Audita maps proposals. Domain validators still
check confidence, applicability, protected glossary terms, and replacement
check applicability, protected glossary terms, and replacement
policy. Model-facing segment IDs are one-based positions within the proposal
request. Generation maps returned references back to the current chunk's actual
request. Generation and repair map those references back to the current chunk's actual
segment IDs, preserving response order and multiple proposals per segment.
Unknown references become invalid-target candidates for the existing domain
checks; they are never interpreted as actual transcript IDs. Debug request
@@ -61,6 +67,17 @@ Module packages call the built-in chain resolver at construction.
## Failure and Outcome Behavior
Each actionable rejection can be revised or withdrawn within its original
section. A revision retains the original proposal identity and must pass the
full validator chain before application.
Before each repair attempt, the runner derives the current proposal's full
before/after text with the same domain preview used by validation. It refreshes
the view after revisions, including changes of target segment. A failed preview
retains available original text and findings without supplying a resulting
segment. This context supplements the original exchange and does not mutate the
transcript. The model-facing fields are described in the [prompt guide](prompts.md).
Module construction failures are fatal. Recoverable proposal model failures
record an unsuccessful operation and yield no candidates for that section;
other sections and module instances continue. Fatal adapter or application
@@ -69,6 +86,11 @@ outcomes are defined by the [report contract](../integrations/output-files.md).
## Changing Modules
Frequently reevaluate the default module combination and sequence against what
has been observed to work best for most workloads. Prior empirical results inform
the current choice without fixing a permanent number or order of passes. Maintain
the selected default in the [configuration contract](../config.md#pipeline-and-glossary-selections).
1. Add or update the narrowly scoped package under `internal/modules/<module_key>`.
2. Keep module prompt selection in the module and its definition in
`internal/prompts`; see [prompt assets](prompts.md).
@@ -86,6 +108,6 @@ outcomes are defined by the [report contract](../integrations/output-files.md).
## Key Tests
- `internal/modules/*/module_test.go`
- `internal/framework/modules/registry_test.go`
- `internal/modules/registry_test.go`
- `internal/framework/proposal_generation/*_test.go`
- `internal/cli/run_test.go` (pipeline/report integration)
- `internal/cli/process_ordered_integration_test.go` (pipeline/report integration)

View File

@@ -12,12 +12,14 @@ selectable values and defaults belong to
Configuration validation checks registry support. CLI orchestration resolves the
selected encoder, passes the final transcript to it, and routes the encoded bytes
to the destination defined by the [CLI contract](../cli.md#streams-and-exit-status).
to the destination defined by the [CLI contract](../cli.md#inspection-and-outcomes).
An unsupported key fails validation or resolution rather than selecting an
implicit fallback.
The registry delegates bare segment serialization to the transcript schema
package and uses an envelope encoder for the versioned form. Report construction
package and uses an envelope encoder for the versioned form. Both serialize
the model's typed segment array directly, including native integer IDs and
omitting empty categories. Report construction
receives the selected key separately; see [report assembly](diagnostics-reporting.md).
## Changing an Encoder

View File

@@ -14,6 +14,7 @@ Executable and command orchestration:
Core deterministic components:
- `internal/core/config`
- `internal/core/glossary`
- `internal/core/schema`
- `internal/core/normalization`
- `internal/core/chunking`
@@ -24,7 +25,7 @@ Core deterministic components:
Framework orchestration and contracts:
- `internal/framework/contracts`
- `internal/framework/modules`
- `internal/framework/preflight`
- `internal/framework/proposal_generation`
- `internal/framework/proposals`
- `internal/framework/runner`
@@ -37,6 +38,7 @@ Framework orchestration and contracts:
- `internal/framework/stagename`
Domain implementations:
- `internal/modules` (built-in module composition)
- `internal/modules/*`
- `internal/validators/*`
- `internal/prompts`
@@ -65,8 +67,8 @@ artifact lifecycle.
## Component Responsibilities
Core components implement configuration defaults/loading/validation/redaction,
transcript and glossary schemas, normalization and chunking, output encoding,
Core components implement configuration defaults, loading, and validation,
transcript schemas and derived glossary views, normalization and chunking, output encoding,
diagnostics artifact helpers, and public report structures.
Framework components implement module and validator contracts, proposal

View File

@@ -4,24 +4,39 @@ The [input contract](../integrations/transcript-glossary-files.md) owns input
formats; [configuration](../config.md) owns settings; the
[output contract](../integrations/output-files.md) owns serialized results.
1. CLI filesystem adapters read transcript and glossary files. Schema parsing
produces source objects; transcript segments enter canonical normalization.
2. Normalization sorts and merges segments using configured time and token
limits, reassigning IDs where needed.
1. CLI loads resolved configuration and transcript input. Preflight checks all
selected glossary views and roles before the output session prepares resources.
Transcript segments then enter canonical normalization.
2. Normalization sorts segments by start time and preserves input order for
ties. It evaluates merge limits using the later end time and the same token
estimate as chunking, then reassigns IDs where needed.
3. The runner partitions the normalized transcript exactly once before its
module loop. Initial section identity, segment membership, and token
estimates stay fixed while text evolves.
4. Module instances execute in configured order. Sections may propose
concurrently, but proposal indices follow section order and response order.
4. Module instances execute in configured order. Each section hands its decoded
proposals and original local segment references to the runner along with
operation facts and any captured exchange. A bounded window admits sections
in order and lets validation and repair proceed as proposals become ready.
The runner assigns final proposal indices in section and response order
when it records completed work. It then writes diagnostics that use those
indices. PromptKit controls provider capacity across all three roles.
5. Deterministic validators precede LLM-backed validators. Every submitted
candidate receives one decision per validator on a normal return. Fatal returns
may preserve a checked subset of completed decisions as diagnostic evidence.
Recoverable failed batches mark their candidates unavailable; successful
survivors continue through all required validators.
6. Only fully approved proposals reach application. Corrections apply in
6. Actionable rejections can enter independent section-local repair branches.
PromptKit coordinates each branch from the captured proposal exchange, owning
its history and additional-turn limit. Each revision, including the final
permitted response, is mapped to the original section and revalidated from the
start. Withdrawal, exhaustion, and recoverable failures finish the branch
without affecting independent approvals.
7. Only fully approved proposals reach application. Corrections apply in
proposal-index order within their owning section. Existing replacement
policies and apply-time safety checks resolve stale conflicts.
7. CLI encodes the final transcript and publishes active files through the
policies and apply-time safety checks resolve stale conflicts. Skip
attribution uses available validation previews of the original text to
distinguish stale edits from defects in a proposal or repair response.
8. CLI encodes the final transcript and publishes active files through the
output session. `framework/processreport` builds one snapshot for YAML,
Markdown, and CLI totals. Debug evidence is captured separately when enabled.
@@ -30,9 +45,15 @@ explicit `not_started`/`interrupted`/`completed` work units, compact model
operation outcomes, and per-module results. Candidate payloads are retained
in the returned output only when debug capture is requested. A work unit can
complete with model errors and applied corrections. Recoverable model failures
never trigger shared cancellation. Fatal setup, internal, application, or
parent-cancellation errors cancel peers, join workers, and preserve earlier
committed module text for partial reports; no completed transcript is published.
never trigger shared cancellation. Fatal failures and parent cancellation stop
further dispatch and join active workers. The initiating error carries its
processing phase and available origin. With ordinary reports enabled, work-unit
evidence includes available peer interruption details. The runner drains active
outcomes and assigns indices to usable proposals from later sections even when
it could not validate them. The working transcript advances at the module's
successful commit boundary.
Earlier committed text remains available to an interrupted run, and transcript
delivery requires successful processing.
Required transcript/report write failures are fatal. Optional debug writes
report safely to stderr without changing decisions or exit status. See

View File

@@ -1,37 +1,54 @@
# Audita Prompt Registry
`internal/prompts` embeds seven PromptKit YAML definitions under
`assets/prompts`. The IDs and selected version remain:
`internal/prompts` embeds eleven PromptKit definitions in the `audita`
collection. The four proposal IDs are `audita/modules.glossary.proposal`,
`audita/modules.homophones.proposal`, `audita/modules.spoken_word.proposal`,
and `audita/modules.grammar.proposal`; the corresponding repair IDs replace
`.proposal` with `.repair`. The three validator IDs are
`audita/validators.spoken_form_plausibility`,
`audita/validators.meaning_reversal_review`, and
`audita/validators.editorial_review`.
- `modules.glossary.proposal` (`v1`)
- `modules.homophones.proposal` (`v1`)
- `modules.spoken_word.proposal` (`v1`)
- `modules.grammar.proposal` (`v1`)
- `validators.spoken_form_plausibility` (`v1`)
- `validators.meaning_reversal_review` (`v1`)
- `validators.editorial_review` (`v1`)
PromptKit composes embedded defaults with operator prompt sources. Shared
instructions come from the embedded fragments in `assets/shared`; the request
shared-variable helper fills absent `HardeningPolicy`, `ProposalContract`,
`RepairContract`, and `ValidationContract` variables. The processing adapter
supplies the embedded instruction fragments for those names. Processing supplies
Audita's response-schema contract separately.
The operator's prompt definition controls which variables its template uses.
Proposal focus and validator acceptance intentionally differ: minor editorial
cleanup may be accepted even when the proposing module was not asked to perform
it. Follow the [architecture boundary](../policy/architecture.md#correction-and-concurrency-invariants)
when maintaining proposal, validation, and repair instructions; the difference
alone is not a reason to tighten validation. The testing rationale is recorded in
[ADR 0003](../adr/0003-module-focus-and-editorial-acceptance.md).
Bundled proposal system messages carry durable correction principles and the
editorial allowance during repair. The initial user message carries each
module's focused proposal assignment and exclusions. Repair can therefore give
a subsequent reassessment assignment without inheriting a system prohibition
on acceptable incidental cleanup. Review complete conversations when editing
these roles, including the transition from a correction set to one repair result.
For a standard request preview or validation, select a native PromptKit profile
and supply the template variables used by the selected prompt. The shipped
proposal definitions use `TranscriptDescriptionBlock`, `GlossaryJSON`,
`ProtectedTermsJSON`, and `SectionJSON`. Glossary entries provide context,
and the separate spelling list defines protection. Preview defaults the
spelling list to `[]` when omitted. The validator definitions use `TranscriptDescriptionBlock` and
`PayloadJSON`. The latter is supplied candidate JSON and does not require a
proposal inference call. Repair definitions use `RepairContract` and
`RepairRequestJSON`, containing the original proposal reference, current
correction, and ordered findings. When the target exists, the request also
includes `original_segment_text`; when the correction is applicable, it includes
`corrected_segment_text`. These fields describe a preview of the current version,
not an applied change. An inapplicable correction omits the resulting text and
retains its findings and available source text. An operator replacement may use
different variables.
See the [upstream CLI reference](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/f369d6a78253b6e6fcb1e023fb2e9c3af1d20ff0/docs/cli.md)
for the standard preview, validation, and smoke commands.
PromptKit reads the embedded definitions as shipped defaults and renders their
messages from named string variables. Operator documents in `profiles_dir` may
contribute native keyed prompt definitions and override an embedded
prompt/version, including its messages and definition-level output settings.
The effective operator text is captured when the runtime is constructed; the
embedded assets remain the source of Audita's shipped task instructions. The
role-bound adapter supplies
`HardeningPolicy` alongside `ProposalContract` and `ValidationContract` from
embedded fragments under `assets/shared`, after caller variables so callers
cannot replace those instructions. Common literal-span and identity guidance
lives in the proposal fragment; shared candidate-reference, context, and
confidence guidance lives in the validation fragment. Module-specific policies
and examples remain in YAML. Proposal prompts receive the section JSON, glossary
JSON where used, and transcript description block. Validator prompts receive
the correction payload and description block.
The embedded prompt assets retain the shipped task instructions and
output-schema association. An operator override controls which template
variables its messages reference: supplying a shared variable does not append
its text when the effective message omits that reference. The role-bound runtime
supplies the complete JSON Schema output contract and repair count; the
definition does not own an operator-facing repair default.
The correction-set schema requires a string replacement and accepts an empty
string. Proposal guidance uses it for eligible span deletion and permits literal
spacing edits; validator guidance evaluates the full before/after segment under
@@ -39,26 +56,32 @@ each validator's existing remit. A blank resulting segment remains a domain
rejection, not a structural schema error.
`internal/framework/responseschema` remains the only embedded source for
`correction_set.v1.json` and `validator_decision_set.v1.json`. It exposes that
`correction_set.v1.json`, `correction_repair.v1.json`, and
`validator_decision_set.v1.json`. It exposes that
filesystem to PromptKit and retains Audita's schema-key lookup. PromptKit's
prepared execution supplies definition and rendered hashes; Audita does not
recompute or promise equality with hashes from the removed template renderer.
The small Audita registry records only prompt ID, version, source, and embedded
path. Prepared runtime metadata belongs in diagnostics rather than the registry.
The small Audita registry records only prompt ID, source, and embedded path. Prepared runtime metadata belongs in diagnostics rather than the registry.
The structured-call contract carries prompt ID/version, string variables,
The structured-call contract carries prompt ID, string variables,
response-schema key, and logical-call attribution. Module and validator callers
pass these values through the role-bound adapter. See the
[LLM runtime](llm-runtime.md) for runtime assembly and
[configuration](../config.md) for operator-selected profiles.
Proposal instructions describe literal matching, each module's replacement policy,
source-based proposal identity, and confidence in whether an edit is warranted.
and source-based proposal identity.
They request independently useful edits and a combined proposal when edits
overlap or depend on one another, while allowing independent edits to share a
segment. This is generation guidance; application still uses the existing
ordering and applicability checks.
Proposal `id` and validator `correction_index` values are short, one-based
references scoped to each request, not internal transcript/proposal identities.
Mapping belongs to [proposal generation](modules.md) and
[validator reconciliation](validators.md). Validator instructions distinguish
confidence in the verdict from the verdict itself. Compact output examples
[validator reconciliation](validators.md). Validator decisions use `approved` for the verdict. Approval examples use an empty
`reason`; rejection guidance requests a specific defect and supplied evidence
within the validator's remit. The model explains defects; repair owns revision or
withdrawal. This is prompt guidance, not a runtime nonempty-reason check. Compact output examples
illustrate the supplied schema without requiring fixed JSON formatting or key
order. The grammar article exception and glossary mishearing exception apply
consistently across their instructions.
@@ -66,3 +89,35 @@ consistently across their instructions.
Only the three active validator definitions are retained. The unused internal
`grammar_review` and `spoken_word_review` definitions and type selections were
removed; built-in chains and operator configuration are unchanged.
Repair guidance reassesses the proposal against the original transcript, context,
and findings. Unsupported, unnecessary, or unresolved uncertain corrections may
be withdrawn, preserving the original text. Otherwise acceptable minor editorial
cleanup remains permissible during repair.
Repair responses keep `proposal_ref` at the root and nest `action` and
`correction` inside `decision`. The schema requires a correction object for
`revise` and `null` for `withdraw`, using a nested union compatible with strict
structured outputs. Mismatched combinations enter PromptKit's configured
structural-repair path before domain decoding. Audita retains its domain check
and verifies the proposal reference. Operator replacement prompts must return
this nested response format; repair request inputs retain their existing shape.
Glossary repair distinguishes the supplied protected spellings from eligible
glossary correction targets; suspected mishearing does not override that protected
list.
Examples contrast meaningful apparent filler with removable hesitation and show
both revision and withdrawal. Treat their words as contextual illustrations,
not unconditional triggers for deletion or replacement.
The meaning-reversal validator has a deliberately narrow remit: reversal of the
full segment's assertion, not every change of meaning. Its prompt distinguishes
changes of referent from reversal and asks rejection reasons to identify the
opposing assertions. Preserve its carefully tuned core instructions when editing;
other validators assess other criteria.
Prompt tests protect rendering with supplied data, resource selection, schemas,
and integration behavior. They do not freeze bundled prose with word/phrase
checks or snapshots. Review editorial intent directly; offline tests cannot
establish live-model editorial quality.

View File

@@ -21,7 +21,6 @@ Execution-class metadata:
Deterministic:
- `proposal_shape`
- `confidence_threshold`
- `original_text_presence`
- `non_empty_resulting_segment` — rejects edits that would leave the segment
blank, regardless of replacement-span length.
@@ -46,9 +45,25 @@ For each module section:
3. record decisions and compact operation outcomes;
4. carry only approved proposals forward.
Decision cardinality is enforced inside Audita: each candidate proposal must
receive exactly one outcome per validator it reaches. The runner still rejects
duplicate, missing, or unknown identities in an internal validator result.
When correction repair is enabled, the runner also gathers independent findings
for rejected candidates when a validator has usable evidence. Unavailable
assessments remain unavailable, and only candidates that pass every applicable
check can advance. A known rejection can enter repair even when another
assessment is unavailable; an unavailable assessment alone does not. Revised
candidates run the applicable checks again. A zero repair budget retains the
original shortlist flow.
The shared validator port lives in `internal/framework/validators`. Instances
may run concurrently across sections and can keep synchronized state. Request
data is borrowed for the duration of the call. Copy data before modifying or
retaining it.
The runner checks decision identity and disposition before allowing a candidate
to advance. A normal return supplies one decision per submitted candidate. A
fatal return may provide a checked subset as evidence. Contradictory approval
and disposition are a fatal contract failure. The recorded disposition governs
approval, and each record carries the effective execution class, including
instance overrides, for initial validation and revalidation.
## LLM Validator Batching
@@ -72,9 +87,7 @@ makes all requested candidates unavailable. Decisions and unavailable indices
map back to internal proposal identities; results are ordered by request identity
and satisfy strict internal cardinality before the runner advances
approved candidates. An unavailable candidate never advances as approved.
Invalid confidence in a decoded test double also makes only its candidate
unavailable; production schema validation still rejects out-of-range confidence
before reconciliation. A partially unavailable batch records one failed
A partially unavailable batch records one failed
operation with only those requested indices, while a successful batch with
ignored extras records a decision-filtering recovery. Fatal errors stop the
chain without returning unchecked candidates as approved. A local result builder
@@ -84,8 +97,11 @@ Reconciliation makes no semantic retry or extra model call; guided recovery rema
[deferred](../roadmap/future.md#domain-aware-response-recovery).
Debug request metadata records `proposal_indices` in local-reference order
(reference 1 is the first entry). Raw decoded responses and ignored indices use
local references; reconciled decisions and unavailable indices use internal
(reference 1 is the first entry). Decoding preserves the supplied numeric
tokens, including integral decimal or exponent spellings. Reconciliation
checks the batch range before converting to a local integer, so an extra
reference beyond the native integer range can be ignored. Raw decoded responses
and ignored indices use local references. Reconciled decisions use internal
proposal indices. Batch token estimates use the same locally numbered payload
as prompt encoding.
@@ -116,19 +132,23 @@ is covered by [report assembly](diagnostics-reporting.md).
- `internal/validators/*_test.go`
- `internal/framework/validators/*_test.go`
- `internal/framework/processreport/correction_ledger_test.go`
- `internal/cli/run_test.go`
- `internal/cli/process_ordered_integration_test.go`
## Supplemental Validation Context
Request construction prepares one segment-position lookup and protected vocabulary
for all candidates. Glossary selection remains candidate-specific, including the
proposed replacement text.
Each stage prepares a context matcher and indexes its selected glossary entries
by identity. Request construction uses a segment-position lookup and returns
matched entries in selection order for each candidate, including matches in the
replacement text. The deterministic guard and application check share the
stage's separate protection matcher.
Each candidate includes the immediately preceding and following source segments
available within its fixed chunk, labeled `preceding` or `following` with speaker,
Each candidate carries its target segment's supplied `speaker`, including an
empty value when no speaker is provided. It also includes the immediately
preceding and following source segments available within its fixed chunk,
labeled `preceding` or `following` with speaker,
text, and categories, plus glossary entries whose names, aliases, or
recognized plurals appear in its original/resulting text or those neighbors.
Glossary matching reuses the protected vocabulary; entries retain glossary order.
Glossary matching uses the same recognition rules; entries retain selection order.
Model-facing candidate and neighboring context omit internal segment IDs.
This supplies evidence such as a troupe definition for a proposed `Jesters`
correction or an adjacent speaker turn explaining deliberate repetition. A correction
@@ -136,15 +156,26 @@ already clear from its own segment does not require such evidence. No audio,
out-of-chunk context, or complete transcript is implied.
Context is serialized inside the validation item and included in the existing
payload token estimate. If one enriched item exceeds the configured limit, optional
neighbors are removed from the end first, then glossary entries from the end,
until it fits or only required candidate data remains. Required before/after text
is never truncated. Existing oversized-candidate handling still applies if that
required data does not fit. Context is supplemental, not a promise that every
relevant definition or neighboring utterance always fits. This uses the existing
payload estimator, not a new guarantee about the provider's full context window.
payload token estimate, including the target speaker. Fitting measures the
required data first, then considers glossary entries followed by neighboring
segments in order. It stops at the first entry that exceeds the budget. Required
before/after text is never truncated. A candidate whose required data exceeds
the budget receives an unavailable decision. The built-in estimator reuses
encoded fragment counts for fitting and batching.
## Protected-Name Repetition
## Protected Names
Protection compares the source segment with the full replacement preview.
Missing and ambiguous spans have no protection verdict. An empty preview can
produce a protection finding alongside the blank-result rule. Application
rechecks the preview against the current segment after earlier edits.
The glossary matcher selects the longest spelling at a match position.
Punctuation-edged spellings use literal edge checks with Go's ASCII regexp
boundary semantics. Active glossary exemptions take part in match selection.
Validation context uses the same scan to select identities in glossary order.
### Protected-Name Repetition
Spoken-word cleanup may reduce repeated protected-name occurrences when every
original protected identity still appears in the resulting segment and surviving
@@ -153,4 +184,4 @@ both a replacement of the repeated phrase and deletion of a redundant span. This
exception only relaxes the deterministic count guard; editorial and meaning-reversal
validation still decide whether the repetition was accidental and the edit preserves
meaning. Intentional emphasis and substantive references remain protected by those
reviews. Other modules retain their existing protection rules.
reviews.

View File

@@ -1,9 +1,12 @@
# Migrating to Audita v2
This guide describes the historical v2 release. For current commands,
configuration, and example projects, use the [v3 migration guide](v3.md).
Audita v2 adopts ConfigKit for configuration and PromptKit for LLM execution.
Version-1 configuration files, environment overlays, and retired flags are not
accepted. Copy a maintained [local](../../examples/minimal-config.yml) or
[service](../../examples/production-config.yml) example, then select real models
accepted. Copy a maintained [local](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.1.1/examples/minimal-config.yml) or
[service](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.1.1/examples/production-config.yml) example, then select real models
in the accompanying `examples/profiles/` files. A testing overlay is shown at
`examples/overlays/testing.yml`; its model choice carries no cost, speed, or
quality guarantee.
@@ -121,8 +124,7 @@ provider attempts. With debug enabled, utilization remains grouped by backend
capacity and usage fields retain known/complete flags. Debug runs write
`effective-config.redacted.yaml`, `selected-profiles.yaml`,
`config-origins.yaml`, `utilization-diagnostics.json`, and
`llm-execution.json`. Request and response artifacts remain redacted debugging
material. See [operations](../operations.md#diagnostics-directory) for placement
`llm-execution.json`. Request and response artifacts are debugging material. See [operations](../operations.md#debug-evidence) for placement
and paths, [configuration](../config.md) for all settings, and the
[CLI reference](../cli.md) for current flags.

41
docs/migrations/v3.md Normal file
View File

@@ -0,0 +1,41 @@
# Migrating to application configuration v3
Audita v4.0.0 adopts application configuration schema v3. Audita v3.1.x uses
schema v2. Set `version: 3` in the application file and move glossary entries into
configuration. Use the [configuration reference](../config.md) and
[maintained examples](../../examples/) for the new formats.
- Replace `pipeline.modules` with ordered `pipeline.stages` records containing
`module` and any per-entry overrides. An explicit empty list runs normalization.
- Define named `glossary_collections` in configuration or its companion imports;
select them using `glossaries` and `protected_terms`. Rename each legacy
entry's `summary` to `description` to preserve its prompt context. Remove
`--glossary` and `--modules` from invocations.
- Move profiles and backends out of the application configuration and retired
`profiles_dir` layout into PromptKit resources. Use its current list records,
IDs, credential sources, and backend admission settings. Select proposal and
validation profiles in application `llm` settings.
- Use the shared `--debug` flag for capture; `diagnostics.work_dir` remains the
parent directory. Review report and output destinations before running.
- Completion counts are hidden by default. Use `--verbose` to see them on
stderr, including when ordinary reports are disabled. `--debug` also shows
counts unless followed by `--quiet`. See [CLI reporting](../cli.md#processing).
## Confidence removal
Remove root `thresholds` and stage `confidence_threshold` settings, and the
`--glossary-confidence-threshold`, `--homophones-confidence-threshold`,
`--spoken-word-confidence-threshold`, and `--grammar-confidence-threshold` flags.
The `confidence_threshold` validator has been removed from the built-in chains.
Update custom proposal, validation, and repair prompts to omit `confidence` from
response examples and instructions. Audita's response schemas no longer accept
that field. Validator responses still require `approved` and `reason`; approvals
may use an empty reason. Corrections in debug records and other affected
serialized proposal/repair data no longer carry confidence, so consumers must
stop requiring or interpreting it. No replacement score or threshold is provided.
Inspect configuration and resources before processing, then try a controlled
small transcript. Processing preflight checks every glossary correction and
selected role before preparing outputs or invoking a model. See [operations](../operations.md)
for lifecycle and recovery.

View File

@@ -1,94 +1,91 @@
# Audita Operations
This guide owns physical output placement and failure handling. The
[CLI reference](cli.md) owns flags and streams, [configuration](config.md) owns
settings, and the [output contract](integrations/output-files.md) owns schemas.
This guide owns output placement and failure handling. The [CLI reference](cli.md)
owns invocation, [configuration](config.md) owns settings, and the
[output contract](integrations/output-files.md) owns serialized formats.
## Normal Workflow
## Processing
1. Validate a version-2 configuration and its selected profiles with
`audita config validate --config config.yml`.
2. Prepare a transcript and glossary following the [input contract](integrations/transcript-glossary-files.md).
3. Run `audita process input.json --config config.yml --glossary glossary.yaml --output corrected.json`.
4. Check the exit status, stderr summary, corrected transcript, and reports.
A completed run can contain recoverable model errors and still apply
corrections that passed every required validator.
Inspect the application and PromptKit resources, prepare a transcript, then run
`audita process` with the desired destination. The [examples](../examples/README.md)
show complete projects. Processing preflight checks every configured glossary
correction and selected profile before output preparation and model work. Empty
protection and an empty pipeline are valid. A completed run can contain
recoverable model errors while still applying independently validated edits.
Correction repair sends the complete original proposal exchange and branch
history to the selected repair provider. A provider rejection ends that branch
as unavailable; other approved edits can still be applied. See
[configuration](config.md#settings) for the attempt budget and profile selection.
## Required Output Files
## Configuration trust
Reporting is enabled by default. For file transcript output, `errors.yml`,
`recoveries.yml`, and `report.md` go in the transcript output's parent directory
unless `--report-dir` is explicitly supplied. For stdout transcript output, they
go in the effective `reporting.stdout_dir` (default `.`), including a
`--report-dir` override. A config-file or overlay value for
`reporting.stdout_dir` alone does not redirect file-output reports. An active
selected report directory must be nonblank. `--reporting=false` suppresses all
three reports and leaves their destination inactive, so it is not probed merely
because `--report-dir` was supplied. It does not suppress the stderr summary or
fatal errors. Stdout contains only transcript JSON; file output leaves it empty.
Treat the selected main file, imports, overlay, and automatically loaded
glossary and prompt companions as one trusted bundle. Choose the working
directory deliberately when using automatic discovery. A bundle can select
the provider, prompt content, and local files consumed by processing. Review
these sources before running with sensitive transcript data. Native inspection
describes the loaded configuration and resources. Processing readiness also
depends on the profiles and glossaries selected by the pipeline. See
[configuration loading](config.md#loading-and-composition) for discovery rules.
Existing report directories and parents for regular transcript files must be
writable. Audita prevents report writes from overwriting transcript, glossary,
loaded application configuration, host YAML discovered under `profiles_dir`,
or host message files referenced by effective PromptKit `content_file` fields,
and rejects conflicting output destinations. Source paths come from the
runtime's captured configuration; unrelated files in the selected directory
remain eligible output destinations. The final transcript may intentionally
replace its own input after successful processing; other input/configuration/
profile sources remain protected.
Preparation never truncates an existing transcript. Device and pipe destinations
(such as `/dev/null` and named pipes) receive ordinary writes at publication time;
they are not opened during preflight or replaced with regular files. A pipe write
can wait for its reader, and stream write errors are fatal. With reporting enabled,
reports still use the output path's parent unless an explicit `--report-dir`
selects another directory; disable reporting when that placement is unsuitable
for a stream destination.
## Outputs and lifecycle
With reporting enabled, all three reports are initialized as `in_progress` before
input processing. Output is encoded fully before publication. Each regular output
file is replaced through a temporary file on its destination filesystem:
transcript first, then `errors.yml`,
`recoveries.yml`, and `report.md`. This is per-file replacement, not a
multi-file transaction. New files honor the process umask; replacing an existing
file preserves its permission bits. A late report error may leave the transcript
published; the process exits nonzero and attempts failed-status reports. On fatal processing
or cancellation, no completed transcript is published, but partial reports are
finalized where possible. An uncatchable termination can leave `in_progress`.
Reporting is enabled by default. For transcript file output, `errors.yml`,
`recoveries.yml`, and `report.md` are placed beside that file unless `--report-dir`
is supplied. For stdout transcript output they use the effective report directory.
Disabling reporting leaves its destination inactive and unprobed. Quiet mode
requires a transcript file or `/dev/null`; it suppresses optional messages, not
failures. Stdout carries transcript JSON when selected.
## Diagnostics Directory
Before processing, Audita checks destination collisions against the transcript,
consumed application and PromptKit sources, and effective host message files. An
intentional in-place transcript replacement is allowed. A regular transcript
output is prepared in a sibling temporary file, leaving the final destination
untouched until successful publication. Pipes and devices are opened only for
delivery, and a pipe can wait for its reader. If a transcript destination changes
between a regular file and a pipe or device during processing, Audita can report a
delivery failure while preserving the new destination. Parent directories for
required outputs must already exist. Publication uses the destinations resolved
during preparation. Give concurrent invocations separate destinations, and
choose separate report directories when retaining reports from multiple runs.
The caller owns these directories and their retention. Later runs can replace
ordinary report files at the same destination.
`--debug` or `diagnostics.debug` enables detailed evidence independently of
reporting. One directory named `run-<id>` is created under
`diagnostics.work_dir` (default `/tmp/audita`), which `--work-dir` can override,
and retained on success or failure. Selecting `--work-dir` alone does not enable
capture. Without debug, no directory or payload files are created. The parent
is created when needed only for debug. Failure to
write optional debug evidence prints a redacted stderr diagnostic but does not
change correction decisions or the exit status.
Enabled reports are initialized as `in_progress` before processing. The
transcript is published before final reports; the files do not form a single
transaction. A late report failure may therefore leave a published transcript.
After a required write failure or cancellation, Audita attempts to clean
unpublished temporary resources and publish failed-status reports. A cleanup
failure is reported with the earlier error. Cancellation observed after a
stream write still fails the invocation, even when some or all bytes reached
the reader. If failed reports cannot be rendered, available report evidence
remains. An uncatchable termination can leave `in_progress` evidence. Use the
exit status and report status to determine the outcome.
Debug evidence includes invocation and effective settings, configuration
origins, selected profiles, redacted source and normalized snapshots,
normalization and initial chunk summaries, all captured proposed candidates
and validator decisions in `correction-ledger.json`, execution/utilization
records, and model interaction files. Individual artifact writes can fail; a
directory's existence does not prove every file was written. These files can
contain transcript text and prompt/response payloads. Configured backend
credentials are redacted, but the transcript itself is not anonymized. Protect
and retain the directory according to the sensitivity of the input.
## Live progress
## Failure Inspection and Recovery
Use `--progress` to follow stage, chunk, proposal, validation, and repair
activity on stderr. Report and transcript files provide the retained outcome.
Debug mode enables live progress by default. Use `--progress=false` to keep
debug evidence with progress disabled.
Exit `0` means processing and every enabled required output completed. Exit
`1` means cancellation, fatal processing, or required-output failure. Exit `2`
identifies usage or configuration/destination selection errors. Recoverable
model-operation failures appear in `errors.yml` as one record per affected
work unit; they do not automatically make the run fail. `recoveries.yml`
records successful operations that needed retry, repair, or proposal filtering.
`report.md` shows every initial chunk and configured module instance, including
interrupted and unattempted work. Ordinary reports omit transcript excerpts and
full decision ledgers; enable debug when those are needed.
## Debug evidence
Read stderr and report status first. If a required output failed after a
transcript was published, do not treat the file alone as proof of a completed
run. Fix the input, service, or destination problem and rerun. Audita has no
resume/checkpoint API.
The shared `--debug` flag enables retained artifacts in a run directory beneath
`diagnostics.work_dir`; selecting a work directory alone does not enable capture.
Optional debug preparation or writes can produce warnings without
changing correction decisions or the required output result. Debug material can
include transcript content, prompts, responses, and correction decisions.
Protect this material according to the sensitivity of the inputs and responses
and manage its retention. Repair interactions
and revalidation artifacts include proposal and attempt coordinates; the
correction ledger connects them to the original edit.
## Recovery
Exit `0` indicates completion of processing and required outputs; nonzero status
indicates an input, processing, cancellation, or required-output failure.
Recoverable model-operation failures and successful repairs or retries are
recorded separately in the ordinary YAML reports. The Markdown matrices identify
pipeline position, module, and optional operator ID. Fix the input, service, or
destination and rerun when necessary; Audita has no resume or checkpoint API.

View File

@@ -4,9 +4,10 @@
Material: All documents under `docs/policy/`, root `AGENTS.md`, and the Policy
Reading Guide in `docs/development.md`, adapted for this repository.
`docs/policy/release.md` incorporates revision
`e833faddf120c789a9b45348edaf75720de16348`; the remaining listed material
incorporates revision `d84a38ebab26f048cafbe59a2246700c35d29843`.
`docs/policy/documentation.md`, `docs/policy/oss.md`, and `docs/policy/release.md`
incorporate revision `593c9b52273c5c879785ae9e995d21026df467b4`.
The remaining listed material incorporates revision
`d84a38ebab26f048cafbe59a2246700c35d29843`.
Copyright (C) 2026 Eric Rakestraw
@@ -15,16 +16,16 @@ SPDX-License-Identifier: CC-BY-SA-4.0
License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE).
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4).
## ConfigKit
Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.7.1`.
Selected module: `go.maximumdirect.net/configkit` at `v1.2.1`.
Copyright (C) 2026 Eric Rakestraw
@@ -32,13 +33,16 @@ SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/6fffde4af8f31f99d3ee295c426eb3234cb0fb77/COPYRIGHT).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/COPYRIGHT).
[Source](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/6fffde4af8f31f99d3ee295c426eb3234cb0fb77).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b).
## ReleaseKit
Selected module: `gitea.maximumdirect.net/eric/ReleaseKit` at `v0.4.1`.
Selected module: `go.maximumdirect.net/releasekit` at `v0.10.0`.
Material: Adapted launcher and tag-delivery recipes in `scripts/release.sh`
and `.woodpecker/release.yml`, attributed to ReleaseKit `v0.9.0`.
Copyright (C) 2026 Eric Rakestraw
@@ -46,83 +50,128 @@ SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/2d5a8110c61e31daf8698766114ae305d0e0e469/COPYRIGHT).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243/COPYRIGHT) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4/COPYRIGHT).
[Source](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/2d5a8110c61e31daf8698766114ae305d0e0e469).
[Source](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/82bac1a3ab935beddd4b8789d1e07f52135d4243).
[Source](https://forge.maximumdirect.net/base-layer/releasekit/src/commit/2180aa868ec2caa95fc8279fd59d5f0ebac41bd4).
## CommandKit
Selected module: `go.maximumdirect.net/commandkit` at `v0.7.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4/COPYRIGHT).
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/b57bfe176cff05a892e6cb07ebb5f350239e55d4).
## CommandKit ckconfig
Selected module: `go.maximumdirect.net/ckconfig` at `v0.9.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745/integrations/ckconfig/COPYRIGHT).
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/9962368f0c1ea1f6ad010638e94621091105d745).
## CommandKit ckprompt
Selected module: `go.maximumdirect.net/ckprompt` at `v0.10.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c9a56e1b15f2169881a91fca4e1f4a1c475e057a/integrations/ckprompt/COPYRIGHT).
[Source](https://forge.maximumdirect.net/base-layer/commandkit/src/commit/c9a56e1b15f2169881a91fca4e1f4a1c475e057a).
## Go runtime and standard library
Selected toolchain: Go 1.26.8 for the distributed Linux binaries.
Selected toolchain: Go 1.27.4 for the distributed Linux binaries.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) |
[LICENSE](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/PATENTS).
[LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/PATENTS).
[Source](https://github.com/golang/go/commit/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e).
[Source](https://github.com/golang/go/commit/7b2881024c95a11ddb86663a616340aa3a88b67f).
## Go vendored golang.org/x/crypto
Material: `golang.org/x/crypto` at `v0.46.1-0.20251210140736-7dacc380ba00` in the Go 1.26.8 standard library.
Material: `golang.org/x/crypto` at `v0.52.1-0.20260526024921-9beb694f9766` in the Go 1.27.4 standard library.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) |
[LICENSE](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/crypto/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/crypto/PATENTS).
[LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/crypto/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/crypto/PATENTS).
[Source](https://github.com/golang/go/commit/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e).
[Source](https://github.com/golang/go/commit/7b2881024c95a11ddb86663a616340aa3a88b67f).
## Go vendored golang.org/x/net
Material: `golang.org/x/net` at `v0.47.1-0.20260731170545-cb1d721f7fb3` in the Go 1.26.8 standard library.
Material: `golang.org/x/net` at `v0.55.1-0.20260731170536-c1d18010be90` in the Go 1.27.4 standard library.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) |
[LICENSE](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/net/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/net/PATENTS).
[LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/net/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/net/PATENTS).
[Source](https://github.com/golang/go/commit/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e).
[Source](https://github.com/golang/go/commit/7b2881024c95a11ddb86663a616340aa3a88b67f).
## Go vendored golang.org/x/sys
Material: `golang.org/x/sys` at `v0.39.0` in the Go 1.26.8 standard library.
Material: `golang.org/x/sys` at `v0.45.0` in the Go 1.27.4 standard library.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) |
[LICENSE](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/sys/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/sys/PATENTS).
[LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/sys/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/sys/PATENTS).
[Source](https://github.com/golang/go/commit/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e).
[Source](https://github.com/golang/go/commit/7b2881024c95a11ddb86663a616340aa3a88b67f).
## Go vendored golang.org/x/text
Material: `golang.org/x/text` at `v0.32.0` in the Go 1.26.8 standard library.
Material: `golang.org/x/text` at `v0.37.0` in the Go 1.27.4 standard library.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) |
[LICENSE](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/text/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/text/PATENTS).
[LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/text/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/text/PATENTS).
[Source](https://github.com/golang/go/commit/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e).
[Source](https://github.com/golang/go/commit/7b2881024c95a11ddb86663a616340aa3a88b67f).
## go-yaml v4
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.
Selected module: `go.yaml.in/yaml/v4` at `v4.0.0`.
Copyright 2006-2010 Kirill Simonov
@@ -134,37 +183,37 @@ SPDX-License-Identifier: Apache-2.0 AND MIT
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[MIT](licenses/MIT-libyaml-v4.txt) |
[NOTICE](https://github.com/yaml/go-yaml/blob/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125/NOTICE).
[NOTICE](https://github.com/yaml/go-yaml/blob/f2f9563503f11b7a60da0c532175dcc693ce8d5a/NOTICE).
[Source](https://github.com/yaml/go-yaml/commit/1c17b9cee72bf81ae73a8be50fbd7dd3a9985125).
[Source](https://github.com/yaml/go-yaml/commit/f2f9563503f11b7a60da0c532175dcc693ce8d5a).
## golang.org/x/text
Selected module: `golang.org/x/text` at `v0.14.0`.
Selected module: `golang.org/x/text` at `v0.44.0`.
Copyright (c) 2009 The Go Authors. All rights reserved.
Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-x-text.txt) |
[LICENSE](https://github.com/golang/text/blob/6c97a165dd661335ff7bce6104a008558123c353/LICENSE) |
[PATENTS](https://github.com/golang/text/blob/6c97a165dd661335ff7bce6104a008558123c353/PATENTS).
[LICENSE](https://github.com/golang/text/blob/6070ac32abcdd1670599eeb3ee4d513c8184a513/LICENSE) |
[PATENTS](https://github.com/golang/text/blob/6070ac32abcdd1670599eeb3ee4d513c8184a513/PATENTS).
[Source](https://github.com/golang/text/commit/6c97a165dd661335ff7bce6104a008558123c353).
[Source](https://github.com/golang/text/commit/6070ac32abcdd1670599eeb3ee4d513c8184a513).
## jsonschema/v6
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.2`.
Selected module: `github.com/santhosh-tekuri/jsonschema/v6` at `v6.0.3`.
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt).
[Source](https://github.com/santhosh-tekuri/jsonschema/commit/29cbed948d24a04700eb94436416b18a07953b71).
[Source](https://github.com/santhosh-tekuri/jsonschema/commit/b0fc661f4939578bc429f408c18202573dbafcc4).
## PromptKit
Selected module: `gitea.maximumdirect.net/eric/promptkit` at `v0.14.0`.
Selected module: `go.maximumdirect.net/promptkit` at `v0.23.2`.
Copyright (C) 2026 Eric Rakestraw
@@ -172,55 +221,34 @@ SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit/src/commit/143c6e9b3a675872117b0471e2ff8bcb25055a54/COPYRIGHT).
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71/COPYRIGHT).
[Source](https://gitea.maximumdirect.net/eric/promptkit/src/commit/143c6e9b3a675872117b0471e2ff8bcb25055a54).
[Source](https://forge.maximumdirect.net/base-layer/promptkit/src/commit/382ccfb14b9630fd8f48c8364dbe2b6159637d71).
## Promptkit OpenRouter Catalog
## Cobra
Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3` at `v3.20260930.0`.
Selected module: `github.com/spf13/cobra` at `v1.10.2`.
Copyright (C) 2026 Eric Rakestraw
Copyright 2013-2023 The Cobra Authors
SPDX-License-Identifier: MIT
License and notices: [MIT](licenses/MIT-Catalogs.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f17d208cb7ad1fb043cda2266cd3011d11b40aa0/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f17d208cb7ad1fb043cda2266cd3011d11b40aa0/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-openrouter/src/commit/f17d208cb7ad1fb043cda2266cd3011d11b40aa0).
## Promptkit Rakestrawhome Catalog
Selected module: `gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3` at `v3.20260930.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: MIT
License and notices: [MIT](licenses/MIT-Catalogs.txt) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/993443d88c451901f4c917fa00c204fd3b54d28d/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/993443d88c451901f4c917fa00c204fd3b54d28d/LICENSE).
[Source](https://gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/src/commit/993443d88c451901f4c917fa00c204fd3b54d28d).
## yaml.v3
Selected module: `gopkg.in/yaml.v3` at `v3.0.1`.
Copyright (c) 2006-2010 Kirill Simonov
Copyright (c) 2006-2011 Kirill Simonov
Copyright (c) 2011-2019 Canonical Ltd
Copyright 2011-2016 Canonical Ltd.
SPDX-License-Identifier: Apache-2.0 AND MIT
SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[MIT](licenses/MIT-libyaml.txt) |
[LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
[NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE).
[LICENSE](https://github.com/spf13/cobra/blob/88b30ab89da2d0d0abb153818746c5a2d30eccec/LICENSE.txt).
[Source](https://github.com/go-yaml/yaml/commit/f6f7691b1fdeb513f56608cd2c32c51f8194bf51).
[Source](https://github.com/spf13/cobra/tree/88b30ab89da2d0d0abb153818746c5a2d30eccec).
## pflag
Selected module: `github.com/spf13/pflag` at `v1.1.0`.
Copyright (c) 2012 Alex Ogier. All rights reserved.
Copyright (c) 2012 The Go Authors. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) |
[LICENSE](https://github.com/spf13/pflag/blob/f8a990678a6d44385313e9b19e40737f889f9b14/LICENSE).
[Source](https://github.com/spf13/pflag/tree/f8a990678a6d44385313e9b19e40737f889f9b14).

View File

@@ -1,4 +1,4 @@
Copyright (c) 2009 The Go Authors. All rights reserved.
Copyright 2009 The Go Authors.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
@@ -10,7 +10,7 @@ notice, this list of conditions and the following disclaimer.
copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the
distribution.
* Neither the name of Google Inc. nor the names of its
* Neither the name of Google LLC nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.

View File

@@ -1,18 +0,0 @@
MIT License
Copyright (c) 2026 Eric Rakestraw
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
associated documentation files (the "Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial
portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
USE OR OTHER DEALINGS IN THE SOFTWARE.

View File

@@ -1,20 +0,0 @@
Copyright (c) 2006-2010 Kirill Simonov
Copyright (c) 2006-2011 Kirill Simonov
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do
so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View File

@@ -2,7 +2,7 @@
**Base Policy Version:** 1.3
**Last Updated**: 2026-09-28
**Last Updated**: 2026-11-15
**Upstream Source:** [Standard Repository Policies architecture](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
## Purpose And Ownership
@@ -72,13 +72,19 @@ hidden global state.
## Correction and Concurrency Invariants
- Module focus guides proposal generation; it is not an exclusive acceptance
boundary. Validators permit otherwise acceptable minor editorial cleanup even
when the originating module did not request it. Existing applicability,
protection, and meaning checks still apply. See
[ADR 0003](../adr/0003-module-focus-and-editorial-acceptance.md) for the empirical
rationale and rejected strict-scope alternative.
- Treat LLM responses as nondeterministic inputs. Preserve deterministic proposal
indexing, validator ordering, transcript mutation, reports, and serialization.
- Validate corrections before final mutation, including local proposal checks,
decision cardinality, and apply-time safety. Provider-side schema enforcement
does not replace these checks.
- Keep LLM concurrency bounded and context-aware through PromptKit's engine-local
per-backend admission. Proposal and validation calls selecting the same backend
- Use PromptKit's context-aware, engine-local per-backend admission for
LLM concurrency. Proposal and validation calls selecting the same backend
share that capacity, including retries and repairs. Preserve deterministic
collection order. Recoverable model-operation failures stay local to their
proposal response or validation batch; fatal invariant/application failure
@@ -113,20 +119,21 @@ subprocess callers. Preserve the stream and exit behavior defined by the
[CLI contract](../cli.md) and the artifact handling defined by
[operations](../operations.md).
Diagnostics, reports, and surfaced errors must not leak configured LLM secrets.
Configuration redaction and LLM payload/error redaction have separate
responsibilities and should remain separate. Implementation details belong in
[diagnostics and reporting](../internal/diagnostics-reporting.md).
## Dependencies
Keep Audita dependency-light and prefer the Go standard library for CLI parsing,
filesystems, synchronization, and tests. ConfigKit owns configuration loading,
presence, provenance, and secret resolution; PromptKit owns prompt/profile
loading, OpenAI-compatible transport, retries, repairs, and backend admission.
Audita owns domain meaning, role selection, and deterministic processing.
Keep Audita dependency-light and prefer the Go standard library where no adopted
library owns the boundary. ConfigKit owns configuration composition, presence,
recorded resolution, and provenance. PromptKit owns prompt, profile, backend,
credential, transport, retry, repair, and admission behavior. CommandKit and its
integrations own command routing and their standard inspection and request
surfaces. Audita owns domain meaning, role selection, transcript processing,
and presentation of its processing results.
Do not introduce broad CLI, dependency-injection, workflow, logging, or plugin
Pass resolved typed configuration to preflight and processing. Preflight checks
execution readiness before output preparation or model work; the output session
owns resources, cleanup, and publication. The glossary and readiness decision is
recorded in [ADR 0002](../adr/0002-glossary-configuration-and-preflight.md).
Do not introduce broad dependency-injection, workflow, logging, or plugin
frameworks without a concrete implemented need and focused tests.
## Testing and Documentation

View File

@@ -1,9 +1,9 @@
# Documentation Policy
**Base Policy Version:** 1.11
**Base Policy Version:** 1.12
**Last Updated**: 2026-09-28
**Upstream Source:** [Standard Repository Policies documentation](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md)
**Last Updated**: 2026-11-11
**Upstream Source:** [Standard Repository Policies documentation](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/documentation.md)
## Purpose
@@ -85,8 +85,8 @@ secret values.
| Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
| Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
| Contributor change recipes | Relevant files under `docs/internal/`, including `docs/internal/cli-config.md`, `docs/internal/modules.md`, and `docs/internal/validators.md` | Concrete editing and validation steps for each component. | Contributor orientation, global policy, and definitions of external contracts. |
| Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, deferred, or rejected work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
| Architectural decision records | `docs/adr/` | Records of significant architectural decisions and supporting rationale. | Ordinary design choices, current behavior reference, implementation status, task sequencing. |
| Future work and implementation status | `docs/roadmap/` | Proposed, accepted, or future work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. |
| Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
| Complete copyable artifacts | `examples/` | Maintained configuration, inputs, and other copyable or runnable files. | Field-by-field reference, command reference, prose explanation. |
@@ -154,8 +154,15 @@ Use sequentially numbered ADR filenames such as
Treat the decision content of an accepted ADR as immutable. When a decision
changes, create a new ADR and update the earlier ADR's status to superseded.
Rejected architectural alternatives belong in the ADR; rejected product ideas
belong in the roadmap.
ADRs should be reserved for major architectural decisions, such as ownership
boundaries, large-scale architectural features, or invariants that rise to
the level of architectural significance. Routine choices, implementation
decisions, and rejected suggestions do not warrant an ADR unless they
otherwise represent a significant architectural decision.
Roadmaps should preserve plausible future work, not rejected product
ideas.
## Maintenance

View File

@@ -1,9 +1,9 @@
# Open Source Licensing And Attribution Policy
**Base Policy Version:** 1.8
**Base Policy Version:** 1.9
**Last Updated**: 2026-09-28
**Upstream Source:** [Standard Repository Policies oss](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md)
**Last Updated**: 2026-11-11
**Upstream Source:** [Standard Repository Policies oss](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/oss.md)
## Purpose And Scope
@@ -64,9 +64,12 @@ license unless the author deliberately changes it. For mixed-purpose projects,
follow the author's selected scope rather than inferring different licenses for
individual packages.
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/application/COPYRIGHT)
or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/library/COPYRIGHT)
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/application/COPYRIGHT)
or [library COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/library/COPYRIGHT)
to create the project’s root `COPYRIGHT` file.
Use the COPYRIGHT examples exactly as provided, except for placeholder
substitutions and changes expressly required or authorized by this policy or
the author.
Use verified project names, contribution years, and copyright holders.
For another selected license, adapt the grant, SPDX expression, disclaimer, and
text references together to reflect the author's selected grant.
@@ -113,7 +116,7 @@ Each entry presents these five fields in order, with blank lines between them:
filenames, such as `COPYRIGHT`, `LICENSE`, `NOTICE`, or `PATENTS`.
5. **Source repository link**, rendered exactly as `[Source](COMMIT_URL).`.
Use the upstream [attribution example](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/attribution.md)
Use the upstream [attribution example](https://gitea.maximumdirect.net/eric/policy/src/commit/a469273adda336625f96b9d769ea27b33999f146/examples/licensing/attribution.md)
to create the project’s `docs/oss/attribution.md`.
The example illustrates omitted fields and multiple copyrights and licenses.
Replace the uppercase placeholders and illustrative URLs with actual component

View File

@@ -1,9 +1,9 @@
# Release Policy
**Base Policy Version:** 1.6
**Base Policy Version:** 1.7
**Last Updated**: 2026-10-08
**Upstream Source:** [Standard Repository Policies release](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md)
**Last Updated**: 2026-11-11
**Upstream Source:** [Standard Repository Policies release](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/release.md)
## Purpose
@@ -82,6 +82,14 @@ For releases at or after `v1.0.0`:
minimum as described below; and
- a patch release may make backward-compatible fixes.
In this context, "backward-compatible" means only that pre-existing, valid
configurations will continue to work following the release. Behavior need not
remain strictly identical.
Audita's minor and patch releases also preserve the documented
[subprocess integration](../integrations/subprocess.md) and
[output-file](../integrations/output-files.md) contracts.
Before `v1.0.0`, a minor release may change a documented public, operational,
configuration, data, integration, or compatibility contract when the release
note explains the impact and required consumer action. A patch release must
@@ -184,6 +192,15 @@ only through an explicit project-specific policy decision explaining the
concrete risk and why ordinary change review or automation is insufficient.
Do not add routine confirmations for checks the command can perform itself.
## Audita's Selected Candidate Checks
Audita uses the module-selected ReleaseKit with race-enabled offline tests, full Go vet,
formatting, Markdown links, module distribution checks, and the required target
builds. Race checks address shared processing and client state; vet and format
checks catch common defects and mechanical drift; link and module checks protect
the distributed source tree. The [runbook](../release.md) specifies the selected
toolchain, native commands, and asynchronous recovery.
## Publication Guards
Automate the checks needed to publish the intended source under a fresh version:

View File

@@ -7,21 +7,21 @@ the release; Woodpecker reports binary delivery separately.
## Prerequisites
Use Bash and Git. The authoritative remote is `origin`,
which must point to `https://gitea.maximumdirect.net/eric/audita.git`; the
Use Bash, Git, a C compiler, and cgo for race detection. The authoritative
remote is `origin`, which must point to `ssh://git@forge.maximumdirect.net:22222/eric/audita.git`; the
primary branch is `main`. Source publication needs no delivery credential.
Woodpecker uses the existing `GITEA_RELEASE_TOKEN` secret for delivery.
The source-build minimum is Go 1.26.0, declared in [go.mod](../go.mod).
This minimum is required by the selected ReleaseKit dependency.
The source-build minimum is Go 1.27.0, declared in [go.mod](../go.mod).
This minimum is required by the selected application dependencies.
Distributed executables do not require a Go installation. The selected release
toolchain is Go 1.26.8, matching the current Woodpecker image and distributed
toolchain is Go 1.27.4, matching the current Woodpecker image and distributed
runtime notices. Use that local installation for tool bootstrap, candidate
validation, and release builds. Replace the installation path below with its
actual directory:
```sh
export PATH="/path/to/go1.26.8/bin:$PATH"
export PATH="/path/to/go1.27.4/bin:$PATH"
export GOTOOLCHAIN=local
go version
```
@@ -42,8 +42,9 @@ GOWORK=off GOTOOLCHAIN=local go mod download
If dependency preparation changes `go.mod` or `go.sum`, include those changes in
the committed candidate. ReleaseKit's CLI is registered as a Go tool dependency;
`go mod tidy` retains its dependencies and checksums. The release wrapper changes
to the repository root and invokes `go tool releasekit` with workspace discovery
and automatic toolchain downloads disabled. Go builds or reuses the selected
to the repository root, selects the host target, and invokes the full
`go.maximumdirect.net/releasekit/cmd/releasekit` tool path with workspace
discovery and automatic toolchain downloads disabled. Go builds or reuses the selected
tool from its normal build cache. Tool preparation precedes offline candidate
validation.
@@ -55,6 +56,24 @@ short summary, relevant compatibility or upgrade instructions, and the required
`COPYRIGHT | LICENSE | ATTRIBUTION` footer with links for the selected version.
Update affected canonical documentation with behavior changes.
For a new major release at v2 or later, migrate the Go module path before
committing the candidate:
1. Change the module path in `go.mod` to end in the selected major suffix, such
as `/v4` for v4.0.0.
2. Update imports of Audita packages throughout application and test code to
match that module path. Update module-path references in build configuration
and scripts where applicable.
3. Update current installation examples and release-note upgrade instructions
to use the new module path and version. Preserve historical release notes.
4. Run `go mod tidy` and include the resulting module metadata in the candidate.
For example, the v4.0.0 cutover changes
`gitea.maximumdirect.net/eric/audita/v3` to
`gitea.maximumdirect.net/eric/audita/v4`. The publication command validates the
prepared candidate; module migration is a source change made during preparation.
The normal candidate tests and target builds below validate the migrated source.
End each note with this footer, substituting its complete tag for `<version>`:
```markdown
@@ -78,9 +97,11 @@ Publish from the repository root, substituting the selected version:
bash scripts/release.sh publish VERSION
```
The command runs `go test -mod=readonly -count=1 ./...` once with module and
toolchain network access disabled, builds the profile's Linux amd64 and arm64
targets, and checks the native version output. It creates an annotated tag whose
The command runs the offline Go test suite with race detection, full Go vet,
formatting, Markdown link, and module distribution checks. Race detection covers
shared processing and client state; vet and formatting catch common Go defects and
mechanical drift; the link and module checks protect the distributed source tree. It builds the
profile's Linux amd64 and arm64 targets and checks the native version output. It creates an annotated tag whose
message comes from the committed note, then pushes the exact tag object. A
successful publication completes the source release without waiting for CI or
checking artifact availability.
@@ -104,11 +125,13 @@ Woodpecker runs ReleaseKit's `ci-deliver` command for tags under
- `SHA256SUMS`
Before running Go, the workflow fetches and verifies the event tag, checks it
out detached, and confirms the source tree is clean. It copies the tagged
out detached, and confirms the source tree is clean. It peels the event object
ID to its commit before comparing it with the tag's commit, accepting both
annotated tag objects and commit IDs from Woodpecker. It copies the tagged
`go.mod` and `go.sum` into temporary module metadata outside the checkout. Go
confirms that this configuration selects ReleaseKit, then builds its CLI using
an alternate `-modfile`. The bootstrap executable and temporary files remain
outside the tagged source. The workflow runs with the selected Go 1.26.8 image,
confirms that this configuration selects ReleaseKit, then invokes its CLI
using an alternate `-modfile` and the host target. Temporary metadata remains
outside the tagged source. The workflow runs with the selected Go 1.27.4 image,
`GOWORK=off`, and `GOTOOLCHAIN=local`.
Delivery uses prepared-checkout mode to verify the existing tag, HEAD, and clean
@@ -117,10 +140,10 @@ worktree without repeating the bootstrap's fetch and checkout.
The resulting executable receives:
```sh
"$${bootstrap_dir}/releasekit" ci-deliver \
go tool -modfile="$${bootstrap_dir}/releasekit.mod" "$${releasekit_module}/cmd/releasekit" ci-deliver \
--repo "$${CI_WORKSPACE}" \
--prepared \
--commit "$${CI_COMMIT_SHA}" \
--commit "$${expected_commit}" \
"$${CI_COMMIT_TAG}"
```
@@ -131,8 +154,8 @@ after source publication; its status and logs report delivery progress or
failure.
ReleaseKit handles content-aware retries and retained-artifact recovery. See
the pinned [publication recovery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.1/docs/consumers/publish.md)
and [delivery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.1/docs/consumers/delivery.md)
the pinned [publication recovery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.10.0/docs/consumers/publish.md)
and [delivery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.10.0/docs/consumers/delivery.md)
for those mechanics. A delivery failure does not undo a confirmed source
release. Retry the same immutable tag after resolving the reported state; do not
replace published files or a checksum manifest.
@@ -145,11 +168,11 @@ captured authoritative endpoint and publication state. Resolve the result
against that endpoint before retrying. An exact remote tag-object match, with
its source available on remote `main`, can confirm publication. If the remote
state cannot be read, the result remains unknown; do not remove or replace the
tag while uncertain. Follow the pinned [publication recovery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.1/docs/consumers/publish.md)
tag while uncertain. Follow the pinned [publication recovery guide](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.10.0/docs/consumers/publish.md)
for object-level recovery details.
A source-release success and artifact-delivery status are separate. For a
partial or uncertain delivery, inspect the job output and follow the pinned
[delivery recovery guidance](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.1/docs/consumers/delivery.md).
[delivery recovery guidance](https://forge.maximumdirect.net/base-layer/releasekit/src/tag/v0.10.0/docs/consumers/delivery.md).
A source or published-content correction requires a new appropriate version;
leave the original tag and its contents intact.

View File

@@ -1,5 +1,7 @@
# Release Notes
- [Audita v4.0.0](v4.0.0.md)
- [Audita v3.1.1](v3.1.1.md)
- [Audita v3.1.0](v3.1.0.md)
- [Audita v3.0.1](v3.0.1.md)
- [Audita v3.0.0](v3.0.0.md)

View File

@@ -38,8 +38,8 @@ profile files require migration from the v2 release format.
3. Select a configuration root whose final definitions are valid. PromptKit now
validates unused definitions too, including backend references, and conflicting
values within a directory source group are errors. The maintained examples
use separate [local](../../examples/profiles/local/) and
[service](../../examples/profiles/service/) roots. Runtime source edits take
use separate [local](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/examples/profiles/local/) and
[service](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/examples/profiles/service/) roots. Runtime source edits take
effect on the next invocation.
4. Rename any application backend literally named `extends` and update its
profile references. ConfigKit now reserves that key for inheritance.
@@ -47,11 +47,11 @@ profile files require migration from the v2 release format.
`audita config validate --config /path/to/config.yml`, including any selected
testing overlay. Application configuration continues to use `version: 2`.
The [configuration reference](../config.md#promptkit-profiles-and-operator-prompts)
contains the migrated format and presence rules. Start from the maintained
[local](../../examples/minimal-config.yml),
[service](../../examples/production-config.yml), or
[application inheritance](../../examples/configkit-inheritance.yml) examples.
The [v3.0.0 configuration reference](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/docs/config.md#promptkit-profiles-and-operator-prompts)
contains the migrated format and presence rules. Start from the
[local](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/examples/minimal-config.yml),
[service](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/examples/production-config.yml), or
[application inheritance](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/examples/configkit-inheritance.yml) examples.
The [CLI reference](../cli.md) describes report selection, and the
[release procedure](../release.md) describes source publication and asynchronous
Linux binary delivery.

20
docs/releases/v3.1.1.md Normal file
View File

@@ -0,0 +1,20 @@
# Audita v3.1.1
This patch fixes the Woodpecker bootstrap failure that prevented Linux binary
delivery for v3.1.0. Audita's transcript processing and configuration are unchanged.
## Changes
- Resolve Woodpecker's tag-event object ID to its source commit before checking
the tagged checkout and invoking ReleaseKit. Annotated tag events previously
failed a comparison between the tag object and commit, stopping the workflow
before binary builds began.
- Add offline regression coverage for annotated and lightweight tag events,
including rejection of an unrelated source commit.
No configuration, profile, transcript-format, or command-behavior migration is
required from v3.1.0. The Go source-build minimum remains 1.26.0. Linux amd64 and
arm64 binary delivery follows the existing asynchronous
[release procedure](../release.md#binary-delivery).
[COPYRIGHT](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.1.1/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.1.1/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.1.1/docs/oss/attribution.md)

95
docs/releases/v4.0.0.md Normal file
View File

@@ -0,0 +1,95 @@
# Audita v4.0.0
Audita v4.0.0 adopts application configuration schema v3 and native library
commands, adds repair of rejected corrections, and improves processing
reliability and resource use. This major release requires migration from
Audita v3.1.x configurations and command invocations.
## Configuration and command migration
- Replace `pipeline.modules` with ordered `pipeline.stages` records. Each entry
can select its own profiles, glossary context, protected terms, validation
budget, and transcript description. Optional stage IDs identify repeated
modules in reports and debug evidence.
- Move standalone glossaries into named `glossary_collections`, composed through
ConfigKit imports and companion files. Select glossary context and protected
terms independently. Replace `--glossary` and `--modules` invocations with the
new configuration and collection-selection flags.
- Move profiles and backends into native PromptKit resources. Application
configuration discovery, overlays, imports, and prompt companions now follow
the adopted library conventions. Processing preflight checks the entire
selected pipeline before preparing outputs or invoking a model.
- Replace `config print-effective` and the curated profile summary with native
configuration and PromptKit inspection commands. Help lists the available
inspection, comparison, preview, validation, and explicit provider smoke
commands.
- Remove confidence thresholds and confidence fields from custom prompts and
response examples. Audita now decides whether to apply corrections through
validation without model-supplied confidence scores.
- Update automation for CommandKit reporting modes. Completion counts require
`--verbose` or `--debug`. Quiet processing requires a transcript file
destination or `/dev/null`. `--debug` enables retained diagnostic artifacts;
`--progress` shows stage, chunk, proposal, validation, and repair activity on
stderr.
Follow the [configuration migration guide](../migrations/v3.md) and
[maintained examples](../../examples/), then inspect the resolved configuration
and try a small transcript. The migration guide's v3 refers to the application
configuration schema. The [CLI reference](../cli.md) owns current commands and
exit semantics.
## Correction quality and recovery
Rejected proposals can be revised using validator feedback and the original
proposal conversation. Correction repair defaults to one attempt per proposal,
can use a separate profile, and can be disabled. Every revision passes through
validation again. Withdrawn, exhausted, and unavailable branches finish
independently while other approved corrections can proceed.
Prompts clarify module focus, incidental editorial cleanup, protected names,
span deletion, and repair outcomes. Missing required validator decisions continue
to affect only their candidates. Recoverable model failures can coexist with a
successful run and applied corrections. See [configuration](../config.md#settings)
for budgets and profile selection.
## Reliability and reports
Processing uses a bounded window of sections within each stage, preserves
deterministic correction identities, and commits stage text after successful
execution. Fatal failures and cancellation stop and join active workers.
Transcript decoding, normalization, chunking, glossary preparation, and evidence
retention use less repeated work and fewer unnecessary copies. An explicit
target section count now produces exactly that many nonempty sections when
feasible and reports infeasible requests as input errors.
Output publication uses checked destinations and retains processing and delivery
failure evidence. Ordinary reports retain schema version 1 and add stage IDs,
correction repair outcomes, and available peer interruption details. See the
[output contract](../integrations/output-files.md) and
[operations guide](../operations.md) for report interpretation and output
lifecycle.
Audita no longer performs application-wide credential substitution in diagnostic
messages or artifacts. Review diagnostic handling before deployment and protect
retained debug data according to the sensitivity of its transcript, prompt, and
response content. Native library inspection retains its own rendering behavior.
Debug artifacts have changed, including removal of confidence fields and the
Audita-owned utilization diagnostics file.
## Dependencies and source builds
Source builds require Go 1.27.0 or newer. Release builds and Woodpecker use
Go 1.27.4. Distributed Linux binaries require no Go installation.
Go module installations use the new `/v4` module path. For example:
```sh
go install gitea.maximumdirect.net/eric/audita/v4/cmd/audita@v4.0.0
```
This release selects ConfigKit v1.2.1, PromptKit v0.23.2, CommandKit v0.7.0,
ckconfig v0.9.0, ckprompt v0.10.0, ReleaseKit v0.10.0, and stable go-yaml v4.0.0.
Audita's direct YAML imports now use v4. Linux amd64 and arm64 remain the
production targets; macOS arm64 receives best-effort development support.
[COPYRIGHT](https://gitea.maximumdirect.net/eric/audita/src/tag/v4.0.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/audita/src/tag/v4.0.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/audita/src/tag/v4.0.0/docs/oss/attribution.md)

View File

@@ -1,6 +1,6 @@
# Deferred Feature Work
**Last updated:** 2026-10-11
**Last updated:** 2026-11-15
**Status:** Deferred or exploratory work; not implemented or scheduled. These
entries preserve work beyond completed feature and library upgrades.
@@ -10,10 +10,11 @@ implementing every capability.
## Domain-Aware Response Recovery
The implemented [partial-success decision reconciliation](../internal/validators.md#llm-validator-batching)
preserves usable decisions without another model call. Guided recovery remains
deferred pending evidence from failures that remain. General per-entry
salvage from structurally invalid responses is also a separate design question;
the accepted reconciliation feature retains whole-response structural validation.
preserves usable decisions without another model call. Revision of rejected
correction proposals is implemented with substantive
validator feedback and explicit proposal withdrawal; see the
[pipeline guide](../internal/pipeline.md).
It is distinct from recovering an unavailable validator decision.
Consider bounded feedback and regeneration for model responses that satisfy the
structural schema but leave requested decisions unavailable after reconciliation.
@@ -30,11 +31,15 @@ secrets, and how regeneration fits bounded budgets and operation deadlines. Reus
shared library capabilities where appropriate; do not introduce an uncoordinated
outer retry loop that multiplies existing retry/repair budgets.
Ordinary editorial rejection is a valid decision, not a reason to regenerate until
an edit is approved. Recovery must preserve required validation, candidate identity,
partial-success safety, and truthful error/recovery reporting. Validate with
controlled responses that distinguish recoverable protocol defects from valid
negative decisions. Exact APIs, budgets, and sequencing remain undecided.
Editorial rejection remains a valid decision about the evaluated proposal. The
implemented correction repair loop handles subsequent revision and full
revalidation; this deferred entry concerns unavailable decisions. Decision recovery
must preserve required validation, candidate identity, partial-success safety,
and truthful error/recovery reporting. Validate with controlled responses that
distinguish protocol defects from valid negative decisions. Exact APIs, budgets,
and sequencing remain undecided. General per-entry salvage from structurally
invalid responses also remains a separate design question; current reconciliation
retains whole-response structural validation.
## Independent Whole-Pipeline Traversal by Chunk
@@ -79,18 +84,15 @@ identity, timestamps, fixed chunks, subsequent stages, recombination, and output
consumers. Do not infer authorization to remove a segment from an empty string
or introduce segment-removal machinery as part of span-deletion consistency.
## Library Inspection and Configuration Comparison
## Live-Model Editorial Evaluation
ConfigKit and PromptKit provide effective-configuration comparison; PromptKit
also provides prompt/profile listings and contextual prompt requirement
inspection. Exposing these capabilities in Audita is deferred until a concrete
operator or development need arises. The dependency upgrade did not select new
inspection commands.
Consider an opt-in transcript corpus and live-model comparisons to assess needed
and unnecessary edits, missed corrections, validator disagreement, and repair
outcomes through independent editorial review. Native PromptKit execution
summaries can supply request and usage measurements. Keep live calls outside
the offline test suite.
If a need emerges, define command ownership, selection syntax, report scope, and
disclosure before implementation. Reuse the libraries' public APIs and consider
shared CLI conventions alongside any separately selected CommandKit adoption.
Requirement discovery is advisory evidence rather than proof of execution
readiness; an empty configuration diff does not prove equivalent execution.
The library-upgrade review remains available in
[Git history](https://gitea.maximumdirect.net/eric/audita/src/commit/4c5536ab78c72dea58d03b3c51834138d429a59a/docs/roadmap/imports.md).
Broader validator context and combined semantic validation remain exploratory.
A proposal to expand context should identify a captured case and the evidence
missing from the validator request.
See the [current validator context](../internal/validators.md#supplemental-validation-context).

82
examples/README.md Normal file
View File

@@ -0,0 +1,82 @@
# Maintained examples
Build Audita from the repository root with Go 1.27 or newer. The commands below
assume the executable is on `PATH`. Each project selects its main file from its
own directory, which also determines companion resources and overlay context.
All models, credentials, names, and endpoints are illustrative.
## Local processing
From `examples/local`, edit `prompts.yml` to match a reachable OpenAI-compatible
local service and its model. Then run:
```sh
audita config validate --config config.yml
audita process --config config.yml --output corrected.json transcript.json
```
Processing makes model requests. Reports are written beside the selected output
unless disabled. For an offline validator preview, from the same directory:
```sh
audita promptkit show prepared audita/validators.meaning_reversal_review \
--config config.yml --profile local \
--var "PayloadJSON=$(cat validation-candidate.json)" \
--var 'TranscriptDescriptionBlock='
```
To preview the repair instruction and its output schema without inference:
```sh
audita promptkit show prepared audita/modules.grammar.repair \
--config config.yml --profile local \
--var "RepairRequestJSON=$(cat repair-candidate.json)"
```
These previews render supplied data without inference. The native command help
and [CLI reference](../docs/cli.md) describe additional inspection and validation.
## Service and overlay
From `examples/service`, edit the synthetic endpoint and models in `prompts.yml`.
Set `AUDITA_EXAMPLE_KEY` to your service credential before a real request. Inspect
without a provider call:
```sh
audita config validate --config config.yml --overlay testing
audita promptkit show profile service-test --config config.yml
```
The example does not promise a provider's model availability, price, or quality.
## Edit a prompt and run again
From `examples/prompt-edit`, inspect the operator replacement:
```sh
audita promptkit show prompt audita/modules.grammar.proposal --config config.yml
```
Edit its message in `prompts.yml`, repeat the inspection, and run `audita process
--config config.yml --output corrected.json transcript.json` against a configured
local service. Each invocation captures the files anew.
## Shared glossary library
From `examples/campaigns`, `first.yml` and `second.yml` each consume the common
`shared.yml` through the companion `glossary.yml`. Inspect each configuration:
```sh
audita config validate --config first.yml
audita config validate --config second.yml
```
With a local service configured, process either campaign:
```sh
audita process --config first.yml --output first-output.json transcript.json
audita process --config second.yml --output second-output.json transcript.json
```
Edit `prompts.yml` for a local service before processing either campaign. The
first uses separate party and spell corrections; the second selects only party.

View File

@@ -0,0 +1,8 @@
version: 3
llm: {proposal_profile: local}
glossaries: [party, spells]
pipeline:
stages:
- {id: names, module: glossary, glossaries: [party]}
- {id: magic, module: glossary, glossaries: [spells]}
- {module: grammar}

View File

@@ -0,0 +1,4 @@
config:
imports:
- path: shared.yml
required: true

View File

@@ -0,0 +1,5 @@
profiles:
- id: local
endpoint: http://localhost:11434/v1
model: example-model
api_key_required: false

View File

@@ -0,0 +1,7 @@
version: 3
llm: {proposal_profile: local}
glossaries: [party]
pipeline:
stages:
- {id: names, module: glossary}
- {module: grammar}

View File

@@ -0,0 +1,12 @@
party:
entries:
- id: lyra
name: Lyra
category: character
description: A fictional adventurer.
spells:
entries:
- id: shield
name: Shield
category: spell
aliases: [Ward]

View File

@@ -0,0 +1,9 @@
[
{
"id": 1,
"speaker": "Narrator",
"start": 0,
"end": 2,
"text": "Lyra raises a ward before the journey."
}
]

View File

@@ -1,15 +0,0 @@
version: 2
profiles_dir: profiles/local
backends:
local-base:
endpoint: http://127.0.0.1:11434/v1
concurrency: 4
queue_capacity: 0
local:
extends: local-base
concurrency: 2
llm:
proposal_profile: local-proposal
validation_profile: local-validation
pipeline:
modules: [grammar]

View File

@@ -0,0 +1,8 @@
version: 3
llm:
proposal_profile: local
pipeline:
stages:
- module: glossary
- module: grammar
glossaries: [party]

View File

@@ -0,0 +1,7 @@
party:
entries:
- id: jesters
name: Jesters
category: faction
description: A traveling group of performers.
aliases: [Jester]

View File

@@ -0,0 +1,5 @@
profiles:
- id: local
endpoint: http://localhost:11434/v1
model: example-model
api_key_required: false

View File

@@ -0,0 +1,17 @@
{
"proposal_ref": 1,
"correction": {
"id": 1,
"original_text": "uh",
"corrected_text": ""
},
"original_segment_text": "uh hello",
"corrected_segment_text": " hello",
"findings": [
{
"validator": "editorial_review",
"reason": "llm_rejected",
"explanation": "Removing only 'uh' leaves unwanted leading whitespace."
}
]
}

View File

@@ -0,0 +1,9 @@
[
{
"id": 1,
"speaker": "Narrator",
"start": 0,
"end": 2,
"text": "The gestures gather beside the stage."
}
]

View File

@@ -0,0 +1 @@
[{"correction_index":1,"speaker":"Narrator","original_text":"not open","corrected_text":"open","original_segment_text":"The door is not open.","corrected_segment_text":"The door is open."}]

View File

@@ -1,13 +0,0 @@
version: 2
profiles_dir: profiles/local
backends:
local:
endpoint: http://127.0.0.1:11434/v1
concurrency: 1
llm:
proposal_profile: local-proposal
validation_profile: local-validation
pipeline:
modules: [grammar]
output:
schema: bare-segments

View File

@@ -1,3 +0,0 @@
llm:
proposal_profile: service-proposal-testing
validation_profile: service-validation-testing

View File

@@ -1,41 +0,0 @@
version: 2
profiles_dir: profiles/service
backends:
service:
endpoint: https://openrouter.ai/api/v1
credential: AUDITA_SERVICE_KEY
concurrency: 2
queue_capacity: 1024
llm:
proposal_profile: service-proposal
validation_profile: service-validation
transient_retries: 2
repair_attempts: 2
operation_timeout: 15m
pipeline:
modules: [glossary, homophones, glossary, spoken_word, grammar]
output:
schema: audita-v1
chunking:
# Requires at least this many normalized segments; omit for automatic chunking.
target_sections: 8
max_section_tokens: 8192
min_section_tokens: 2048
normalization:
max_segment_gap: 4.0
ellipsis_gap: 3.5
max_segment_duration: 60.0
max_segment_tokens: 2048
thresholds:
glossary: 0.8
homophones: 0.8
spoken_word: 0.8
grammar: 0.8
context:
description: "General context for domain vocabulary and speaker names."
reporting:
enabled: true
stdout_dir: .
diagnostics:
debug: false
work_dir: /tmp/audita

View File

@@ -1,8 +0,0 @@
profiles:
local-proposal:
backend: local
model: replace-with-local-model
temperature: 0
max_tokens: 2048
top_p: 1
timeout_seconds: 120

View File

@@ -1,8 +0,0 @@
profiles:
local-validation:
backend: local
model: replace-with-local-model
temperature: 0
max_tokens: 1024
top_p: 1
timeout_seconds: 120

View File

@@ -1,8 +0,0 @@
profiles:
service-proposal-testing:
backend: service
model: replace-with-testing-model
temperature: 0
max_tokens: 2048
top_p: 1
timeout_seconds: 120

View File

@@ -1,8 +0,0 @@
profiles:
service-proposal:
backend: service
model: replace-with-provider-model
temperature: 0
max_tokens: 2048
top_p: 1
timeout_seconds: 120

View File

@@ -1,8 +0,0 @@
profiles:
service-validation-testing:
backend: service
model: replace-with-testing-model
temperature: 0
max_tokens: 1024
top_p: 1
timeout_seconds: 120

View File

@@ -1,8 +0,0 @@
profiles:
service-validation:
backend: service
model: replace-with-provider-model
temperature: 0
max_tokens: 1024
top_p: 1
timeout_seconds: 120

View File

@@ -0,0 +1,8 @@
version: 3
llm:
proposal_profile: local
pipeline:
stages:
- module: glossary
- module: grammar
glossaries: [party]

View File

@@ -0,0 +1,7 @@
party:
entries:
- id: jesters
name: Jesters
category: faction
description: A traveling group of performers.
aliases: [Jester]

View File

@@ -0,0 +1,23 @@
profiles:
- id: local
endpoint: http://localhost:11434/v1
model: example-model
api_key_required: false
collections:
audita:
prompts:
- id: modules.grammar.proposal
messages:
- role: system
content: Correct only clearly supported grammatical errors.
- role: user
content: |
{{ .ProposalContract }}
{{ .HardeningPolicy }}
{{ .TranscriptDescriptionBlock }}
Glossary: {{ .GlossaryJSON }}
Transcript: {{ .SectionJSON }}
output:
format: json
validation_mode: json_schema
schema_path: correction_set.v1.json

View File

@@ -0,0 +1,9 @@
[
{
"id": 1,
"speaker": "Narrator",
"start": 0,
"end": 2,
"text": "The gestures gather beside the stage."
}
]

View File

@@ -0,0 +1,7 @@
version: 3
llm:
proposal_profile: service-proposal
validation_profile: service-review
pipeline:
stages:
- module: grammar

View File

@@ -0,0 +1,3 @@
llm:
proposal_profile: service-test
validation_profile: service-test

View File

@@ -0,0 +1,16 @@
backends:
- id: service
endpoint: https://example.invalid/v1
api_key_env: AUDITA_EXAMPLE_KEY
concurrency_limit: 2
queue_capacity: 8
profiles:
- id: service-proposal
backend: service
model: example-proposal-model
- id: service-review
backend: service
model: example-review-model
- id: service-test
extends: {id: service-proposal}
model: example-testing-model

View File

@@ -0,0 +1,9 @@
[
{
"id": 1,
"speaker": "Narrator",
"start": 0,
"end": 2,
"text": "The gestures gather beside the stage."
}
]

View File

@@ -1,6 +0,0 @@
glossary:
- name: Audita
aliases:
- audita
category: product
summary: The Audita transcript correction CLI.

34
go.mod
View File

@@ -1,25 +1,25 @@
module gitea.maximumdirect.net/eric/audita/v3
module gitea.maximumdirect.net/eric/audita/v4
go 1.26.0
go 1.27.0
require (
gitea.maximumdirect.net/eric/ConfigKit v0.7.1
gitea.maximumdirect.net/eric/ReleaseKit v0.4.1
gitea.maximumdirect.net/eric/promptkit v0.14.0
golang.org/x/mod v0.40.0
gopkg.in/yaml.v3 v3.0.1
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3
go.maximumdirect.net/ckconfig v0.9.0
go.maximumdirect.net/ckprompt v0.10.0
go.maximumdirect.net/commandkit v0.7.0
go.maximumdirect.net/configkit v1.2.1
go.maximumdirect.net/promptkit v0.23.2
go.maximumdirect.net/releasekit v0.10.0
go.yaml.in/yaml/v4 v4.0.0
)
require (
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3 v3.20260930.0 // indirect
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3 v3.20260930.0 // indirect
github.com/kr/pretty v0.3.1 // indirect
github.com/rogpeppe/go-internal v1.14.1 // indirect
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect
github.com/yuin/goldmark/v2 v2.1.6 // indirect
go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect
golang.org/x/text v0.14.0 // indirect
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
github.com/inconshreveable/mousetrap v1.1.0 // indirect
github.com/spf13/cobra v1.10.2 // indirect
github.com/spf13/pflag v1.1.0 // indirect
github.com/yuin/goldmark/v2 v2.1.16 // indirect
golang.org/x/mod v0.43.0 // indirect
golang.org/x/text v0.44.0 // indirect
)
tool gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit
tool go.maximumdirect.net/releasekit/cmd/releasekit

68
go.sum
View File

@@ -1,39 +1,35 @@
gitea.maximumdirect.net/eric/ConfigKit v0.7.1 h1:q3HrX4WWCPt1WfMydqFEaAmCf9s6Dq+vknJj0C/mdcI=
gitea.maximumdirect.net/eric/ConfigKit v0.7.1/go.mod h1:C82sbyKHYMV1OwaD2GJanFrwTfcZfjlW2JsGze5b0kA=
gitea.maximumdirect.net/eric/ReleaseKit v0.4.1 h1:Qn+mdebYOzCVCEXgCbuGSO/WHmJtItwaQ8e3XwY3qtI=
gitea.maximumdirect.net/eric/ReleaseKit v0.4.1/go.mod h1:LVodqNQ3OIKv9NBq+fFeyMByd1lHY25YOmmpah/NaNI=
gitea.maximumdirect.net/eric/promptkit v0.14.0 h1:HUzlcrFk18dNGPBgnHqjAw87O0c9Wl/IC1xc/VmzL10=
gitea.maximumdirect.net/eric/promptkit v0.14.0/go.mod h1:2YGvNca3bNXZP+e+pJeGzsNUcxwkHvzvuoc+LNNiT3E=
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3 v3.20260930.0 h1:lzfCDbzJQRGzIlRPRprnAV9hVVL5zUQy80VMQ0kbYa0=
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3 v3.20260930.0/go.mod h1:HjS0f+3q0IdHCTEz+VVAEgIwIWJFAZUjuKdAtvtqKdg=
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3 v3.20260930.0 h1:h12ZTRldAmpLAomj0oQRGteFxHLN1LPE6XDl9zJNbm8=
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3 v3.20260930.0/go.mod h1:OEFBeKdjTsLzqJwLmXI2O5gG3r64FktcVJVb3mBrRfg=
github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
github.com/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI=
github.com/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs=
github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ=
github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
github.com/yuin/goldmark/v2 v2.1.6 h1:igy0q9JcqovoFXFx/XjtU8sHVhcUHavPj2sA3EoKJUE=
github.com/yuin/goldmark/v2 v2.1.6/go.mod h1:G6M4/qOFtfn01/o14BU1UR2Lo5N3S9Qo7xCuz/sHjGQ=
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/mod v0.40.0 h1:hUv+3cXcdRHz08UmSiOob7sadHig73uo5bkXxQ/tvUs=
golang.org/x/mod v0.40.0/go.mod h1:0/weTWkPWGBikyTWAX3dkjVztMmBA5hM0DH6BElSupE=
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ=
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spf13/pflag v1.1.0 h1:6W6MbVUrnMb8PEhjkqwsVLY7ryuzRfFHF4mQd7L94ag=
github.com/spf13/pflag v1.1.0/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/yuin/goldmark/v2 v2.1.16 h1:MXvCVo+Cb2SVJ5cwJUzXetDjI7HECRJCkcqylEQtcJo=
github.com/yuin/goldmark/v2 v2.1.16/go.mod h1:G6M4/qOFtfn01/o14BU1UR2Lo5N3S9Qo7xCuz/sHjGQ=
go.maximumdirect.net/ckconfig v0.9.0 h1:s9Ikga4wt4K1NpLCX9bLhm5vbcm1Fgqy9yk2lmO4Sss=
go.maximumdirect.net/ckconfig v0.9.0/go.mod h1:yGjFVr2UzjJjiwDdMwsKehuQfvvtv7rTEOIk5NQOY00=
go.maximumdirect.net/ckprompt v0.10.0 h1:t2UyWSke+bWH9aTDrw5/bteD+TO0y5LD0NWw0y2KniQ=
go.maximumdirect.net/ckprompt v0.10.0/go.mod h1:vx8lZnelASctQtyxY2yV4PuTZfLpE9EqDa+LPj3+SHM=
go.maximumdirect.net/commandkit v0.7.0 h1:toLDGhHoVe6gBX5HWuzQ/Joz0cBqEhJXolW21m3axBk=
go.maximumdirect.net/commandkit v0.7.0/go.mod h1:sVp3JXKpm2YrP4Ie8Q3nWmQgwBdPN8uO+wQU72erDns=
go.maximumdirect.net/configkit v1.2.1 h1:f+/6WjNl6CULbMr6ZSVwi4aty9rmuDfJlvpeU7I+HZM=
go.maximumdirect.net/configkit v1.2.1/go.mod h1:ewu6blSokUDCMovy8JBXAdXRikGmlHXAQpFghnPWRfs=
go.maximumdirect.net/promptkit v0.23.2 h1:nE+Qqqbw5GN4PHD2e5OEWUHXcYkESZm3ryZVBsKWwFQ=
go.maximumdirect.net/promptkit v0.23.2/go.mod h1:vPFg76VXcffP0JBFMS2WADCHwV5FYvO2O4bvIoiDlwc=
go.maximumdirect.net/releasekit v0.10.0 h1:3GOgaIigXTkvYaRkntWZASE//2NTR1+IhkoKmt64aJo=
go.maximumdirect.net/releasekit v0.10.0/go.mod h1:cT5NZNEcf7SKDx4MPG40YNK9V4bNyIxcLLFuNlbGQ90=
go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
go.yaml.in/yaml/v4 v4.0.0 h1:/LG1pNO84Z4l603j/xMn69CcS5OYhMQ/f7l2LoQUGuw=
go.yaml.in/yaml/v4 v4.0.0/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
golang.org/x/mod v0.43.0 h1:MFuq5J6s35W9D3IjkwyWc9vHh0nENOrt5K8Iof4ofmg=
golang.org/x/mod v0.43.0/go.mod h1:4ec1JnuyBz5+FIVhg86UsA39YG8BpnrZdJYSNHmGzHY=
golang.org/x/text v0.44.0 h1:YItdp/mQNGnsmrgpcdA5yQ3bnRxCfo/Tj/iByGW9GGo=
golang.org/x/text v0.44.0/go.mod h1:S4FR1waQ9LbjQTls97SyRjDaUUVkaM+cXwwuG/G+MwY=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

110
internal/cli/app_wiring.go Normal file
View File

@@ -0,0 +1,110 @@
package cli
import (
"context"
"fmt"
"net/http"
"reflect"
"strings"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/config"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/llm"
"gitea.maximumdirect.net/eric/audita/v4/internal/prompts"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/ckprompt"
commandkit "go.maximumdirect.net/commandkit"
ck "go.maximumdirect.net/configkit"
pk "go.maximumdirect.net/promptkit"
"go.maximumdirect.net/releasekit/buildinfo"
)
type invocationState struct {
engines []engineEntry
client *http.Client
}
type engineEntry struct {
selection ckconfig.Selection
engine *pk.Engine
}
func loadApplication(ctx context.Context, selection ckconfig.Selection, _ struct{}, _ *invocationState) (*ck.Result[config.Config], error) {
if err := ctx.Err(); err != nil {
return nil, err
}
var source ck.Source
if selection.Config.Set {
if strings.TrimSpace(selection.Config.Value) == "" {
return nil, fmt.Errorf("--config requires a nonempty path")
}
source = ck.File(selection.Config.Value)
} else {
source = ck.SearchConfig("audita", ck.Searches(ck.WorkingDirectory(), ck.UserConfigDirectory(), ck.UnixSystemDirectories()))
}
return config.Load(ck.Input{Source: source}, selection.Overlay.Value, selection.Overrides...)
}
func loadPromptEngine(ctx context.Context, selection ckconfig.Selection, input struct{}, state *invocationState) (*pk.Engine, error) {
loaded, err := loadApplication(ctx, selection, input, state)
if err != nil {
return nil, err
}
var client *http.Client
if state != nil {
client = state.client
}
return llm.NewEngine(ctx, loaded, client)
}
func capturePromptEngine(ctx context.Context, selection ckconfig.Selection, input struct{}, state *invocationState) (*pk.Engine, error) {
if state != nil {
for _, entry := range state.engines {
if reflect.DeepEqual(entry.selection, selection) {
return entry.engine, nil
}
}
}
engine, err := loadPromptEngine(ctx, selection, input, state)
if err != nil {
return nil, err
}
if state != nil {
state.engines = append(state.engines, engineEntry{selection: selection, engine: engine})
}
return engine, nil
}
func buildApplication(extra ...commandkit.Declaration) (*commandkit.App, error) {
return buildApplicationWithClient(nil, extra...)
}
func buildApplicationWithClient(client *http.Client, extra ...commandkit.Declaration) (*commandkit.App, error) {
appScope := ckconfig.FromConfigKit("app", "Audita application settings.", loadApplication)
appScope.Features.Overrides = true
promptScope := ckprompt.ConfigScope(loadPromptEngine)
configCommand := ckconfig.Command(ckconfig.Suite[struct{}, *invocationState]{NewState: func() *invocationState { return &invocationState{client: client} }, Scopes: []ckconfig.Scope[struct{}, *invocationState]{appScope, promptScope}})
definitions := ckprompt.WithNamespaces(ckprompt.FromEngine(capturePromptEngine), pk.Namespaces{})
definitions.NewState = func() *invocationState { return &invocationState{client: client} }
definitions = ckprompt.WithRequestValidation(definitions, capturePromptEngine, func(_ context.Context, seed ckprompt.ValidationRequest, _ struct{}, _ *invocationState) (pk.RunRequest, error) {
return applicationPromptRequest(seed.Request, seed.Namespaces), nil
})
definitions = ckprompt.WithRequestPreparation(definitions, capturePromptEngine, func(_ context.Context, seed ckprompt.PreparationRequest, _ struct{}, _ *invocationState) (pk.RunRequest, error) {
return applicationPromptRequest(seed.Request, seed.Namespaces), nil
})
definitions = ckprompt.WithSmokeTesting(definitions, capturePromptEngine, nil)
declarations := []commandkit.Declaration{configCommand, commandkit.Completion("audita"), processCommand()}
declarations = append(declarations, ckprompt.Declarations(definitions)...)
declarations = append(declarations, extra...)
return commandkit.New(commandkit.Identity{Name: "audita", Version: buildinfo.Version()}, declarations...)
}
// applicationPromptRequest supplies instructions only for Audita's maintained prompts.
func applicationPromptRequest(request pk.RunRequest, namespaces *pk.Namespaces) pk.RunRequest {
id := request.PromptID
if !strings.Contains(id, "/") && namespaces != nil && namespaces.Prompt != "" {
id = namespaces.Prompt + "/" + id
}
if _, ok := prompts.LookupMetadata(id); ok {
request.Vars = prompts.WithSharedVariables(request.Vars)
}
return request
}

View File

@@ -0,0 +1,232 @@
package cli
import (
"bytes"
"context"
"encoding/json"
"io"
"net/http"
"os"
"path/filepath"
"strings"
"testing"
"go.maximumdirect.net/ckconfig"
"go.maximumdirect.net/ckprompt"
commandkit "go.maximumdirect.net/commandkit"
pk "go.maximumdirect.net/promptkit"
)
func TestNativeConfigurationAndResourceCommands(t *testing.T) {
dir := t.TempDir()
file := filepath.Join(dir, "config.yml")
if err := os.WriteFile(file, []byte("version: 3\ncontext:\n description: example\n"), 0644); err != nil {
t.Fatal(err)
}
app, err := buildApplication()
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
args []string
contains string
}{
{[]string{"--help"}, "audita"},
{[]string{"version"}, "audita"},
{[]string{"process", "--help"}, "transcript"},
{[]string{"config", "show", "--scope", "app", "--config", file}, "example"},
{[]string{"promptkit", "list", "prompts", "--config", file}, "audita/modules.grammar.proposal"},
} {
var out, stderr bytes.Buffer
result := app.Execute(context.Background(), tc.args, commandkit.Streams{Out: &out, Err: &stderr})
if result.Status != 0 || !strings.Contains(out.String(), tc.contains) {
t.Errorf("%v: status=%d out=%q err=%q", tc.args, result.Status, out.String(), stderr.String())
}
}
}
func TestNativeConfigurationSelectionsAndComparison(t *testing.T) {
dir := t.TempDir()
first, second := filepath.Join(dir, "first.yml"), filepath.Join(dir, "second.yml")
for name, data := range map[string]string{first: "context:\n description: before\n", second: "context:\n description: after\n"} {
if err := os.WriteFile(name, []byte(data), 0644); err != nil {
t.Fatal(err)
}
}
app, err := buildApplication()
if err != nil {
t.Fatal(err)
}
var out, stderr bytes.Buffer
outcome := app.Execute(context.Background(), []string{"config", "diff", "--details", "--check", "--scope=app", "--config", first, "--against-config", second, "--set=/context/description=\"left\"", "--against-set=/context/description=\"right\""}, commandkit.Streams{Out: &out, Err: &stderr})
if outcome.Status != 3 || !strings.Contains(out.String(), "left") || !strings.Contains(out.String(), "right") {
t.Fatalf("status=%d output=%q err=%q", outcome.Status, out.String(), stderr.String())
}
out.Reset()
stderr.Reset()
outcome = app.Execute(context.Background(), []string{"config", "show", "--scope=app", "--config", filepath.Join(dir, "missing.yml")}, commandkit.Streams{Out: &out, Err: &stderr})
if outcome.Status == 0 {
t.Fatalf("missing file accepted: %s", out.String())
}
}
func TestExplicitEmptyConfigurationPathFails(t *testing.T) {
app, err := buildApplication()
if err != nil {
t.Fatal(err)
}
var out, stderr bytes.Buffer
result := app.Execute(context.Background(), []string{"config", "show", "--scope=app", "--config="}, commandkit.Streams{Out: &out, Err: &stderr})
if result.Status == 0 {
t.Fatal("explicit empty path accepted")
}
}
func TestPromptConfigurationComparisonAcquiresEqualSelectionsIndependently(t *testing.T) {
dir := t.TempDir()
main := filepath.Join(dir, "config.yml")
if err := os.WriteFile(main, []byte("version: 3\n"), 0600); err != nil {
t.Fatal(err)
}
resource := filepath.Join(dir, "prompts.yml")
writeProfile := func(model string) {
t.Helper()
if err := os.WriteFile(resource, []byte("profiles: [{id: local, model: "+model+"}]\n"), 0600); err != nil {
t.Fatal(err)
}
}
writeProfile("before")
scope := ckprompt.ConfigScope(func(ctx context.Context, selection ckconfig.Selection, input struct{}, state *invocationState) (*pk.Engine, error) {
engine, err := loadPromptEngine(ctx, selection, input, state)
writeProfile("after")
return engine, err
})
side := ckconfig.ComparisonSide[struct{}]{Selection: ckconfig.Selection{
Config: commandkit.Supplied[string]{Value: main, Set: true},
}}
result, err := scope.Compare(context.Background(), ckconfig.ComparisonRequest[struct{}]{Left: side, Right: side}, &invocationState{})
if err != nil {
t.Fatal(err)
}
for _, difference := range result.Value {
if strings.Contains(difference.Left.YAML, "before") && strings.Contains(difference.Right.YAML, "after") {
return
}
}
t.Fatal("comparison did not capture the model before and after the resource changed")
}
func TestRequestInspectionAndExplicitSmokeUseSameSources(t *testing.T) {
dir := t.TempDir()
file := filepath.Join(dir, "config.yml")
if err := os.WriteFile(file, []byte("version: 3\n"), 0644); err != nil {
t.Fatal(err)
}
resources := `backends:
- id: local
endpoint: https://example.invalid/v1
smoke_tests:
default_profile: fixture
authentication:
kind: none
profiles:
- id: fixture
backend: local
model: sample
collections:
audita:
prompts:
- id: modules.grammar.proposal
messages:
- role: user
content: 'Replacement {{.HardeningPolicy}} {{.SectionJSON}}'
output:
format: text
validation_mode: none
`
if err := os.WriteFile(filepath.Join(dir, "prompts.yml"), []byte(resources), 0644); err != nil {
t.Fatal(err)
}
calls := 0
client := &http.Client{Transport: roundTripFunc(func(req *http.Request) (*http.Response, error) {
calls++
body := `{}`
if req.Method == http.MethodPost {
requestBody, err := io.ReadAll(req.Body)
if err != nil {
t.Fatal(err)
}
content := "PROMPTKIT_OK"
if strings.Contains(string(requestBody), "response_format") {
content = `{"status":"ok"}`
}
encoded, err := json.Marshal(content)
if err != nil {
t.Fatal(err)
}
body = `{"model":"sample","choices":[{"message":{"content":` + string(encoded) + `}}]}`
}
return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(body)), Request: req}, nil
})}
app, err := buildApplicationWithClient(client)
if err != nil {
t.Fatal(err)
}
execute := func(args ...string) (commandkit.Outcome, string, string) {
t.Helper()
var out, stderr bytes.Buffer
result := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &stderr})
return result, out.String(), stderr.String()
}
common := []string{"--config", file, "--llm-profile", "fixture"}
args := append([]string{"promptkit", "show", "prepared", "audita/modules.grammar.proposal"}, common...)
args = append(args, "--llm-var", "SectionJSON=[]", "--llm-var", "HardeningPolicy=custom-instruction")
outcome, out, stderr := execute(args...)
if outcome.Status != 0 || !strings.Contains(out, "Replacement custom-instruction") {
t.Fatalf("preview status=%d out=%q err=%q", outcome.Status, out, stderr)
}
args = append([]string{"promptkit", "requirements", "validate", "audita/validators.editorial_review"}, common...)
args = append(args, "--llm-var", `PayloadJSON=[{"correction_index":1,"original_segment_text":"teh cat","corrected_segment_text":"the cat"}]`, "--llm-var", "TranscriptDescriptionBlock=")
outcome, out, stderr = execute(args...)
if outcome.Status != 0 {
t.Fatalf("validator status=%d out=%q err=%q", outcome.Status, out, stderr)
}
validatorPreview := append([]string{"promptkit", "show", "prepared", "audita/validators.editorial_review"}, common...)
validatorPreview = append(validatorPreview, "--llm-var", `PayloadJSON=[{"correction_index":1,"original_segment_text":"teh cat","corrected_segment_text":"the cat"}]`, "--llm-var", "TranscriptDescriptionBlock=")
outcome, out, stderr = execute(validatorPreview...)
if outcome.Status != 0 || !strings.Contains(out, "teh cat") {
t.Fatalf("validator preview status=%d out=%q err=%q", outcome.Status, out, stderr)
}
if calls != 0 {
t.Fatalf("inspection made %d provider calls", calls)
}
outcome, out, stderr = execute("promptkit", "test", "reachability", "--config", file, "--llm-backend", "local")
if outcome.Status != 0 || calls == 0 {
t.Fatalf("smoke status=%d calls=%d out=%q err=%q", outcome.Status, calls, out, stderr)
}
previous := calls
outcome, out, stderr = execute("promptkit", "test", "all", "--config", file, "--llm-backend", "local", "--llm-profile", "fixture", "--format=json")
if outcome.Status != 0 || calls <= previous || !strings.Contains(out, "structured_output") || !strings.Contains(out, "text_inference") {
t.Fatalf("aggregate status=%d calls=%d out=%q err=%q", outcome.Status, calls, out, stderr)
}
}
type roundTripFunc func(*http.Request) (*http.Response, error)
func (f roundTripFunc) RoundTrip(req *http.Request) (*http.Response, error) { return f(req) }
func TestRequestDefaultsRespectNamespaceAndCallerVariables(t *testing.T) {
request := pk.RunRequest{PromptID: "modules.grammar.proposal", Vars: map[string]string{"HardeningPolicy": "caller"}}
result := applicationPromptRequest(request, &pk.Namespaces{Prompt: "audita"})
if result.Vars["HardeningPolicy"] != "caller" || result.Vars["ProposalContract"] == "" {
t.Fatalf("variables=%v", result.Vars)
}
if _, changed := request.Vars["ProposalContract"]; changed {
t.Fatal("input variables mutated")
}
generic := pk.RunRequest{PromptID: "generic", Vars: map[string]string{"x": "y"}}
result = applicationPromptRequest(generic, nil)
if len(result.Vars) != 1 || result.Vars["x"] != "y" {
t.Fatalf("generic request changed: %v", result.Vars)
}
}

View File

@@ -1,233 +0,0 @@
package cli
import (
"errors"
"flag"
"fmt"
"io"
"os"
"path/filepath"
"strconv"
"strings"
ck "gitea.maximumdirect.net/eric/ConfigKit"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/config"
)
var systemConfigPaths = []string{"/usr/local/etc/audita/config.yml", "/etc/audita/config.yml"}
type configInput struct {
ConfigPath string
ConfigPathSet bool
Overlay string
View string
TranscriptPath string
GlossaryPath string
OutputPath string
ReportDirSet bool
Overrides []ck.Override
}
type selectedConfig struct {
Path string
Source string
Result *ck.Result[config.Config]
}
// parseConfigInput owns the common setting flags and process-only path flags.
// A transcript before flags and one after flags are both accepted.
func parseConfigInput(command string, args []string, output io.Writer) (configInput, bool, error) {
var input configInput
fs := flag.NewFlagSet(command, flag.ContinueOnError)
fs.SetOutput(output)
configPath := fs.String("config", "", "Main configuration YAML file")
overlay := fs.String("overlay", "", "Selected configuration overlay")
if command == "print-effective" {
fs.String("view", "settings", "Effective view: settings, profiles, or explain")
}
settingPaths := map[string]ck.Path{
"proposal-profile": ck.Keys("llm", "proposal_profile"),
"validation-profile": ck.Keys("llm", "validation_profile"),
"output-schema": ck.Keys("output", "schema"),
"validation-max-prompt-tokens": ck.Keys("validation", "max_prompt_tokens"),
"target-sections": ck.Keys("chunking", "target_sections"),
"max-section-tokens": ck.Keys("chunking", "max_section_tokens"),
"min-section-tokens": ck.Keys("chunking", "min_section_tokens"),
"normalize-max-segment-gap": ck.Keys("normalization", "max_segment_gap"),
"normalize-ellipsis-gap": ck.Keys("normalization", "ellipsis_gap"),
"normalize-max-segment-duration": ck.Keys("normalization", "max_segment_duration"),
"normalize-max-segment-tokens": ck.Keys("normalization", "max_segment_tokens"),
"glossary-confidence-threshold": ck.Keys("thresholds", "glossary"),
"homophones-confidence-threshold": ck.Keys("thresholds", "homophones"),
"spoken-word-confidence-threshold": ck.Keys("thresholds", "spoken_word"),
"grammar-confidence-threshold": ck.Keys("thresholds", "grammar"),
"transcript-description": ck.Keys("context", "description"),
"reporting": ck.Keys("reporting", "enabled"),
"report-dir": ck.Keys("reporting", "stdout_dir"),
"debug": ck.Keys("diagnostics", "debug"),
"work-dir": ck.Keys("diagnostics", "work_dir"),
"modules": ck.Keys("pipeline", "modules"),
}
for name := range settingPaths {
switch name {
case "reporting", "debug":
fs.Bool(name, false, "Setting override")
case "validation-max-prompt-tokens", "target-sections", "max-section-tokens", "min-section-tokens", "normalize-max-segment-tokens":
fs.Int(name, 0, "Setting override")
case "normalize-max-segment-gap", "normalize-ellipsis-gap", "normalize-max-segment-duration", "glossary-confidence-threshold", "homophones-confidence-threshold", "spoken-word-confidence-threshold", "grammar-confidence-threshold":
fs.Float64(name, 0, "Setting override")
default:
fs.String(name, "", "Setting override")
}
}
if command == "process" {
fs.String("glossary", "", "Glossary YAML file")
fs.String("output", "", "Corrected transcript output file")
}
parseArgs := args
front := ""
if command == "process" && len(args) > 0 && !strings.HasPrefix(args[0], "-") {
front, parseArgs = args[0], args[1:]
}
if err := fs.Parse(parseArgs); err != nil {
if errors.Is(err, flag.ErrHelp) {
return configInput{}, true, nil
}
return configInput{}, false, err
}
positions := fs.Args()
if front != "" {
positions = append([]string{front}, positions...)
}
if command == "process" {
if len(positions) != 1 {
return configInput{}, false, fmt.Errorf("expected exactly one transcript JSON path")
}
input.TranscriptPath = positions[0]
input.GlossaryPath = fs.Lookup("glossary").Value.String()
input.OutputPath = fs.Lookup("output").Value.String()
if strings.TrimSpace(input.GlossaryPath) == "" {
return configInput{}, false, fmt.Errorf("--glossary is required")
}
} else if len(positions) != 0 {
return configInput{}, false, fmt.Errorf("unexpected positional arguments")
}
input.ConfigPath, input.Overlay = *configPath, *overlay
if command == "print-effective" {
input.View = fs.Lookup("view").Value.String()
switch input.View {
case "settings", "profiles", "explain":
default:
return configInput{}, false, fmt.Errorf("unknown effective view %q", input.View)
}
}
fs.Visit(func(f *flag.Flag) {
if f.Name == "config" {
input.ConfigPathSet = true
}
if f.Name == "report-dir" {
input.ReportDirSet = true
}
path, ok := settingPaths[f.Name]
if !ok {
return
}
var value any = f.Value.String()
switch f.Name {
case "reporting", "debug":
value, _ = strconv.ParseBool(f.Value.String())
case "modules":
modules, err := config.ParseModulesCSV(f.Value.String())
if err != nil {
value = err
} else {
values := make([]any, len(modules))
for i, module := range modules {
values[i] = module
}
value = values
}
case "validation-max-prompt-tokens", "target-sections", "max-section-tokens", "min-section-tokens", "normalize-max-segment-tokens":
value, _ = strconv.Atoi(f.Value.String())
case "normalize-max-segment-gap", "normalize-ellipsis-gap", "normalize-max-segment-duration", "glossary-confidence-threshold", "homophones-confidence-threshold", "spoken-word-confidence-threshold", "grammar-confidence-threshold":
value, _ = strconv.ParseFloat(f.Value.String(), 64)
}
input.Overrides = append(input.Overrides, ck.Override{Path: path, Value: value, Flag: "--" + f.Name})
})
for _, override := range input.Overrides {
if err, ok := override.Value.(error); ok {
return configInput{}, false, fmt.Errorf("%s: %w", override.Flag, err)
}
}
return input, false, nil
}
func selectConfigPath(explicit string, set bool, stat func(string) (os.FileInfo, error), candidates []string) (string, string, error) {
if set {
if strings.TrimSpace(explicit) == "" {
return "", "", fmt.Errorf("--config requires a nonempty path")
}
if _, err := stat(explicit); err != nil {
return "", "", fmt.Errorf("config file %q: %w", explicit, err)
}
return explicit, "flag", nil
}
for _, path := range candidates {
if _, err := stat(path); err == nil {
return path, "default", nil
} else if !os.IsNotExist(err) {
return "", "", fmt.Errorf("config file %q: %w", path, err)
}
}
return "", "", fmt.Errorf("no configuration file found; select a config with backend and profile settings")
}
func loadConfigInput(input configInput, command string) (selectedConfig, error) {
if command == "validate" && (!input.ConfigPathSet || strings.TrimSpace(input.ConfigPath) == "") {
return selectedConfig{}, fmt.Errorf("--config is required")
}
path, source, err := selectConfigPath(input.ConfigPath, input.ConfigPathSet, os.Stat, systemConfigPaths)
if err != nil {
return selectedConfig{}, err
}
loaded, err := config.Load(ck.File(path), input.Overlay, input.Overrides...)
if err != nil {
return selectedConfig{}, err
}
return selectedConfig{Path: path, Source: source, Result: loaded}, nil
}
func configInputError(err error) string {
var loadErr *ck.LoadError
if !errors.As(err, &loadErr) {
return err.Error()
}
var messages []string
for _, diagnostic := range loadErr.Diagnostics() {
messages = append(messages, diagnostic.Message)
}
if len(messages) == 0 {
return err.Error()
}
return strings.Join(messages, "; ")
}
func selectedReportDir(cfg config.Config, outputPath string, reportDirSet bool) (string, error) {
if !cfg.Reporting.Enabled {
return "", nil
}
var reportDir string
if outputPath != "" {
if reportDirSet {
reportDir = cfg.Reporting.StdoutDir
} else {
reportDir = filepath.Dir(outputPath)
}
} else {
reportDir = cfg.Reporting.StdoutDir
}
if strings.TrimSpace(reportDir) == "" {
return "", fmt.Errorf("report directory is required when reporting is enabled for the selected destination")
}
return reportDir, nil
}

View File

@@ -1,280 +0,0 @@
package cli
import (
"errors"
"io"
"os"
"path/filepath"
"strings"
"testing"
ck "gitea.maximumdirect.net/eric/ConfigKit"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/config"
)
func TestSharedConfigInput(t *testing.T) {
for _, command := range []string{"process", "validate", "print-effective"} {
t.Run(command, func(t *testing.T) {
args := []string{"--config", "main.yml", "--overlay", "testing", "--proposal-profile", "economy", "--modules", "", "--target-sections", "0"}
if command == "process" {
args = append([]string{"transcript.json", "--glossary", "glossary.yml"}, args...)
}
input, help, err := parseConfigInput(command, args, io.Discard)
if err != nil || help {
t.Fatalf("parse: %+v %v %v", input, help, err)
}
if !input.ConfigPathSet || input.ConfigPath != "main.yml" || input.Overlay != "testing" || len(input.Overrides) != 3 {
t.Fatalf("selection: %+v", input)
}
for _, override := range input.Overrides {
switch override.Path.String() {
case ck.Keys("pipeline", "modules").String():
if values, ok := override.Value.([]any); !ok || len(values) != 0 {
t.Fatalf("empty modules: %#v", override.Value)
}
case ck.Keys("chunking", "target_sections").String():
if override.Value != 0 {
t.Fatalf("zero target: %#v", override.Value)
}
}
}
})
}
}
func TestConfigInputRejectsRemovedAndProcessOnlyFlags(t *testing.T) {
for _, command := range []string{"process", "validate", "print-effective"} {
for _, flag := range []string{"--model", "--llm-api-key", "--max-retries", "--llm-concurrency", "--report-json", "--work-dir-retention"} {
args := []string{flag, "value"}
if command == "process" {
args = append([]string{"transcript.json", "--glossary", "glossary.yml"}, args...)
}
if _, _, err := parseConfigInput(command, args, io.Discard); err == nil {
t.Fatalf("%s accepted %s", command, flag)
}
}
}
for _, command := range []string{"validate", "print-effective"} {
if _, _, err := parseConfigInput(command, []string{"--glossary", "glossary.yml"}, io.Discard); err == nil {
t.Fatalf("%s accepted process path", command)
}
if _, _, err := parseConfigInput(command, []string{"transcript.json"}, io.Discard); err == nil {
t.Fatalf("%s accepted positional", command)
}
}
for _, command := range []string{"process", "validate", "print-effective"} {
_, help, err := parseConfigInput(command, []string{"--help"}, io.Discard)
if err != nil || !help {
t.Fatalf("%s help: %v %v", command, help, err)
}
}
}
func TestConfigSelection(t *testing.T) {
dir := t.TempDir()
first, second := filepath.Join(dir, "first.yml"), filepath.Join(dir, "second.yml")
if err := os.WriteFile(second, []byte("version: 2\n"), 0600); err != nil {
t.Fatal(err)
}
path, source, err := selectConfigPath("", false, os.Stat, []string{first, second})
if err != nil || path != second || source != "default" {
t.Fatalf("discovery: %q %q %v", path, source, err)
}
for _, tc := range []struct {
explicit string
set bool
candidates []string
}{
{"", true, []string{second}}, {first, true, []string{second}}, {"", false, []string{first}},
} {
if _, _, err := selectConfigPath(tc.explicit, tc.set, os.Stat, tc.candidates); err == nil {
t.Fatalf("accepted unavailable selection: %+v", tc)
}
}
statDenied := func(string) (os.FileInfo, error) { return nil, os.ErrPermission }
if _, _, err := selectConfigPath("", false, statDenied, []string{first}); !errors.Is(err, os.ErrPermission) {
t.Fatalf("inaccessible candidate: %v", err)
}
path, source, err = selectConfigPath(second, true, os.Stat, []string{first})
if err != nil || path != second || source != "flag" {
t.Fatalf("explicit path: %q %q %v", path, source, err)
}
}
func TestLegacyEnvironmentDoesNotSelectConfig(t *testing.T) {
t.Setenv("AUDITA_CONFIG", filepath.Join(t.TempDir(), "legacy.yml"))
_, _, err := selectConfigPath("", false, os.Stat, []string{filepath.Join(t.TempDir(), "missing.yml")})
if err == nil || !strings.Contains(err.Error(), "no configuration file") {
t.Fatalf("legacy environment changed discovery: %v", err)
}
}
func TestEffectiveViewParsing(t *testing.T) {
for _, view := range []string{"settings", "profiles", "explain"} {
input, _, err := parseConfigInput("print-effective", []string{"--view", view}, io.Discard)
if err != nil || input.View != view {
t.Fatalf("%q: %+v %v", view, input, err)
}
}
if _, _, err := parseConfigInput("print-effective", []string{"--view", "raw"}, io.Discard); err == nil {
t.Fatal("unknown view accepted")
}
if _, _, err := parseConfigInput("validate", []string{"--view", "profiles"}, io.Discard); err == nil {
t.Fatal("validate accepted inspection-only flag")
}
}
func TestSharedLoadingUsesSelectedFileOverlayAndVisitedOverrides(t *testing.T) {
dir := t.TempDir()
if err := os.Mkdir(filepath.Join(dir, "overlays"), 0700); err != nil {
t.Fatal(err)
}
main := filepath.Join(dir, "config.yml")
base := "version: 2\nbackends:\n local:\n endpoint: https://local.invalid/v1\nllm:\n proposal_profile: base\nchunking:\n max_section_tokens: 900\n"
if err := os.WriteFile(main, []byte(base), 0600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(dir, "overlays", "testing.yml"), []byte("llm:\n proposal_profile: testing\n"), 0600); err != nil {
t.Fatal(err)
}
for _, command := range []string{"process", "validate", "print-effective"} {
args := []string{"--config", main, "--overlay", "testing", "--min-section-tokens", "500"}
if command == "process" {
args = append([]string{"input.json", "--glossary", "glossary.yml"}, args...)
}
input, _, err := parseConfigInput(command, args, io.Discard)
if err != nil {
t.Fatal(err)
}
selected, err := loadConfigInput(input, command)
if err != nil {
t.Fatal(err)
}
c := selected.Result.Config
if c.LLM.ProposalProfile != "testing" || c.LLM.ValidationProfile != "testing" || c.Chunking.MinSectionTokens != 500 || c.Chunking.MaxSectionTokens != 900 {
t.Fatalf("%s resolved %+v", command, c)
}
}
input, _, err := parseConfigInput("validate", []string{"--overlay", "testing"}, io.Discard)
if err != nil {
t.Fatal(err)
}
if _, err := loadConfigInput(input, "validate"); err == nil {
t.Fatal("validate accepted discovery")
}
input, _, err = parseConfigInput("validate", []string{"--config", main}, io.Discard)
if err != nil {
t.Fatal(err)
}
if _, err := loadConfigInput(input, "validate"); err == nil {
t.Fatal("unmodified invalid lower-precedence section relation accepted")
}
}
func TestReportingAndDebugOverridesRemainIndependent(t *testing.T) {
dir := t.TempDir()
if err := os.Mkdir(filepath.Join(dir, "overlays"), 0700); err != nil {
t.Fatal(err)
}
main := filepath.Join(dir, "config.yml")
base := "version: 2\nbackends:\n local:\n endpoint: https://local.invalid/v1\nllm:\n proposal_profile: base\n"
if err := os.WriteFile(main, []byte(base), 0600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(dir, "overlays", "testing.yml"), []byte("reporting:\n enabled: true\n stdout_dir: reports\ndiagnostics:\n debug: true\n"), 0600); err != nil {
t.Fatal(err)
}
defaultInput, _, err := parseConfigInput("validate", []string{"--config", main}, io.Discard)
if err != nil {
t.Fatal(err)
}
defaults, err := loadConfigInput(defaultInput, "validate")
if err != nil {
t.Fatal(err)
}
if !defaults.Result.Config.Reporting.Enabled || defaults.Result.Config.Reporting.StdoutDir != "." || defaults.Result.Config.Diagnostics.Debug {
t.Fatalf("unexpected defaults: %+v", defaults.Result.Config)
}
for _, command := range []string{"process", "validate", "print-effective"} {
args := []string{"--config", main, "--overlay", "testing", "--reporting=false", "--debug=false"}
if command == "process" {
args = append([]string{"input.json", "--glossary", "glossary.yml"}, args...)
}
input, _, err := parseConfigInput(command, args, io.Discard)
if err != nil {
t.Fatal(err)
}
if len(input.Overrides) != 2 || input.Overrides[0].Value != false || input.Overrides[1].Value != false {
t.Fatalf("boolean overrides must remain typed: %+v", input.Overrides)
}
selected, err := loadConfigInput(input, command)
if err != nil {
t.Fatal(err)
}
if selected.Result.Config.Reporting.Enabled || selected.Result.Config.Diagnostics.Debug || selected.Result.Config.Reporting.StdoutDir != "reports" {
t.Fatalf("%s did not honor explicit false: %+v", command, selected.Result.Config)
}
}
processInput, _, err := parseConfigInput("process", []string{"input.json", "--glossary", "glossary.yml", "--config", main, "--overlay", "testing"}, io.Discard)
if err != nil {
t.Fatal(err)
}
processConfig, err := loadConfigInput(processInput, "process")
if err != nil {
t.Fatal(err)
}
if got, err := selectedReportDir(processConfig.Result.Config, filepath.Join("out", "corrected.json"), processInput.ReportDirSet); err != nil || got != "out" {
t.Fatalf("overlay stdout directory redirected file output: %q %v", got, err)
}
}
func TestReportDirectorySelectionOnlyUsesActiveDestination(t *testing.T) {
cfg := config.Config{Reporting: config.Reporting{Enabled: true, StdoutDir: "reports"}}
if got, err := selectedReportDir(cfg, "", false); err != nil || got != "reports" {
t.Fatalf("stdout destination: %q %v", got, err)
}
if got, err := selectedReportDir(cfg, filepath.Join("out", "corrected.json"), false); err != nil || got != "out" {
t.Fatalf("file destination ignored stdout setting: %q %v", got, err)
}
if got, err := selectedReportDir(cfg, filepath.Join("out", "corrected.json"), true); err != nil || got != "reports" {
t.Fatalf("explicit file report directory: %q %v", got, err)
}
cfg.Reporting.StdoutDir = ""
if got, err := selectedReportDir(cfg, filepath.Join("out", "corrected.json"), false); err != nil || got != "out" {
t.Fatalf("inactive blank configured report directory rejected for file output: %q %v", got, err)
}
if _, err := selectedReportDir(cfg, filepath.Join("out", "corrected.json"), true); err == nil {
t.Fatal("active explicit blank report directory accepted for file output")
}
if _, err := selectedReportDir(cfg, "", false); err == nil {
t.Fatal("enabled stdout reporting accepted blank destination")
}
cfg.Reporting.Enabled = false
if got, err := selectedReportDir(cfg, filepath.Join("out", "corrected.json"), true); err != nil || got != "" {
t.Fatalf("disabled reporting probed destination: %q %v", got, err)
}
}
func TestBareBooleanFlagsAndReportDirectoryOverride(t *testing.T) {
input, _, err := parseConfigInput("process", []string{"input.json", "--glossary", "glossary.yml", "--reporting", "--debug", "--report-dir", "reports"}, io.Discard)
if err != nil {
t.Fatal(err)
}
values := map[string]any{}
for _, override := range input.Overrides {
values[override.Path.String()] = override.Value
}
if values[ck.Keys("reporting", "enabled").String()] != true || values[ck.Keys("diagnostics", "debug").String()] != true || values[ck.Keys("reporting", "stdout_dir").String()] != "reports" {
t.Fatalf("incorrect visited overrides: %+v", values)
}
if !input.ReportDirSet {
t.Fatal("explicit --report-dir presence was not recorded")
}
withoutReportDir, _, err := parseConfigInput("process", []string{"input.json", "--glossary", "glossary.yml"}, io.Discard)
if err != nil {
t.Fatal(err)
}
if withoutReportDir.ReportDirSet {
t.Fatal("absent --report-dir was recorded as explicit")
}
}

View File

@@ -0,0 +1,150 @@
package cli
import (
"bytes"
"context"
"encoding/json"
"io"
"net/http"
"os"
"path/filepath"
"runtime"
"strings"
"sync"
"sync/atomic"
"testing"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/config"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/llm"
ck "go.maximumdirect.net/configkit"
)
func TestMaintainedProjectsWithControlledProvider(t *testing.T) {
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("cannot locate examples")
}
root := filepath.Join(filepath.Dir(file), "..", "..", "examples")
t.Setenv("AUDITA_EXAMPLE_KEY", "synthetic-example-key")
for _, tc := range []struct{ dir, main, overlay string }{
{"local", "config.yml", ""}, {"service", "config.yml", "testing"},
{"prompt-edit", "config.yml", ""}, {"campaigns", "first.yml", ""}, {"campaigns", "second.yml", ""},
} {
t.Run(tc.dir+"/"+tc.main, func(t *testing.T) {
main := filepath.Join(root, tc.dir, tc.main)
loaded, err := config.Load(ck.Input{Source: ck.File(main)}, tc.overlay)
if err != nil {
t.Fatal(err)
}
loaded.Config.Reporting.Enabled = false
var calls atomic.Int32
var mu sync.Mutex
var models, prompts []string
transport := controlledTransport(func(r *http.Request) (*http.Response, error) {
calls.Add(1)
var request struct {
Model string `json:"model"`
Messages []struct {
Content string `json:"content"`
} `json:"messages"`
}
if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
return nil, err
}
var content strings.Builder
for _, message := range request.Messages {
content.WriteString(message.Content)
}
mu.Lock()
models = append(models, request.Model)
prompts = append(prompts, content.String())
mu.Unlock()
return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"model":"fixture","choices":[{"message":{"role":"assistant","content":"{\"corrections\":[]}"}}]}`)), Request: r}, nil
})
engine, err := llm.NewRuntime(context.Background(), loaded, &http.Client{Transport: transport})
if err != nil {
t.Fatal(err)
}
raw, err := os.ReadFile(filepath.Join(root, tc.dir, "transcript.json"))
if err != nil {
t.Fatal(err)
}
source, err := schema.ParseSourceTranscriptJSON(raw)
if err != nil {
t.Fatal(err)
}
inputs := &processInputs{Configuration: loaded, Runtime: engine, Source: source}
prepared, err := prepareProcess(context.Background(), processInput{Transcript: filepath.Join(root, tc.dir, "transcript.json")}, inputs, &bytes.Buffer{})
if err != nil {
t.Fatal(err)
}
defer prepared.Prepared.Output.Close()
if _, err := executePipeline(context.Background(), inputs, prepared, source.Canonical(), func(error) {}, nil); err != nil {
t.Fatal(err)
}
if int(calls.Load()) != len(loaded.Config.Pipeline.Stages) {
t.Fatalf("provider calls=%d", calls.Load())
}
if tc.dir == "service" && (len(models) != 1 || models[0] != "example-testing-model") {
t.Fatalf("overlay models=%v", models)
}
if tc.dir == "campaigns" && tc.main == "first.yml" {
if len(prompts) != 3 || !strings.Contains(prompts[0], `"name": "Lyra"`) || strings.Contains(prompts[0], `"name": "Shield"`) || !strings.Contains(prompts[1], `"name": "Shield"`) || strings.Contains(prompts[1], `"name": "Lyra"`) {
t.Fatalf("campaign glossary selections: %v", prompts)
}
}
if tc.dir == "campaigns" && tc.main == "second.yml" {
if len(prompts) != 2 || !strings.Contains(prompts[0], `"name": "Lyra"`) || strings.Contains(prompts[0], `"name": "Shield"`) {
t.Fatalf("second campaign glossary selection: %v", prompts)
}
}
})
}
}
func TestExamplePromptEditIsCapturedOnNextLoad(t *testing.T) {
_, file, _, ok := runtime.Caller(0)
if !ok {
t.Fatal("cannot locate examples")
}
source := filepath.Join(filepath.Dir(file), "..", "..", "examples", "prompt-edit")
dir := t.TempDir()
for _, name := range []string{"config.yml", "glossary.yml", "prompts.yml"} {
raw, err := os.ReadFile(filepath.Join(source, name))
if err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(dir, name), raw, 0600); err != nil {
t.Fatal(err)
}
}
inspect := func() string {
loaded, err := config.Load(ck.Input{Source: ck.File(filepath.Join(dir, "config.yml"))}, "")
if err != nil {
t.Fatal(err)
}
engine, err := llm.NewRuntime(context.Background(), loaded, nil)
if err != nil {
t.Fatal(err)
}
prompt, err := engine.Engine.InspectPrompt(context.Background(), "audita/modules.grammar.proposal")
if err != nil {
t.Fatal(err)
}
return prompt.Messages[0].Content
}
before := inspect()
filePath := filepath.Join(dir, "prompts.yml")
raw, err := os.ReadFile(filePath)
if err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filePath, []byte(strings.Replace(string(raw), "clearly supported grammatical errors", "clearly supported punctuation errors", 1)), 0600); err != nil {
t.Fatal(err)
}
after := inspect()
if !strings.Contains(before, "grammatical errors") || !strings.Contains(after, "punctuation errors") {
t.Fatalf("before=%q after=%q", before, after)
}
}

View File

@@ -1,442 +1,110 @@
package cli
import (
"bytes"
"context"
"crypto/rand"
"encoding/hex"
"errors"
"fmt"
"io"
"strings"
"sync"
"time"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/chunking"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/config"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/diagnostics"
coreio "gitea.maximumdirect.net/eric/audita/v3/internal/core/io"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/normalization"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/outputschema"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/redaction"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/reporting"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/contracts"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/llm"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/modules"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/outcomes"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/processreport"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/runner"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/structuredoutput"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/normalization"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/outputschema"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/reporting"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/llm"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/preflight"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/runner"
"go.maximumdirect.net/ckconfig"
commandkit "go.maximumdirect.net/commandkit"
ck "go.maximumdirect.net/configkit"
)
func runProcess(ctx context.Context, args []string, stdout, stderr io.Writer) int {
input, help, err := parseConfigInput("process", args, stderr)
// processResult carries the runner's transcript and ordinary report facts.
type processResult struct {
Transcript *schema.Transcript
Snapshot reporting.Snapshot
}
func runProcess(inv commandkit.Invocation, input processInput) commandkit.Outcome {
loaded, err := loadProcessInputs(inv.Context, input, inv.ReportingMode())
if err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", configInputError(err))
return 2
}
if help {
writeProcessUsage(stdout)
return 0
}
selected, err := loadConfigInput(input, "process")
if err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", configInputError(err))
return 2
}
cfg := selected.Result.Config
reportDir, err := selectedReportDir(cfg, input.OutputPath, input.ReportDirSet)
if err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", llm.RedactError(err, cfg))
return 2
}
if cfg.Diagnostics.Debug && strings.TrimSpace(cfg.Diagnostics.WorkDir) == "" {
fmt.Fprintln(stderr, "audita process: debug work directory is required")
return 2
}
if err := ctx.Err(); err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", err)
return 1
}
runtime, err := llm.NewRuntime(ctx, cfg, selected.Path, nil)
if err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", llm.RedactError(err, cfg))
if ctx.Err() != nil || llm.IsAssetError(err) {
return 1
if canceled := inv.Context.Err(); canceled != nil && !errors.Is(err, canceled) {
err = errors.Join(err, canceled)
}
return 2
}
specs, err := contracts.ResolveModuleRunSpecs(cfg.Pipeline.Modules)
if err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", llm.RedactError(err, cfg))
return 2
}
runID, err := generateRunID()
if err != nil {
fmt.Fprintf(stderr, "audita process: run ID: %s\n", llm.RedactError(err, cfg))
return 1
}
started := time.Now().UTC()
state := &processState{cfg: cfg, runtime: runtime, specs: specs, runID: runID, started: started,
transcriptPath: input.TranscriptPath, glossaryPath: input.GlossaryPath, outputPath: input.OutputPath,
selected: selected, overlay: input.Overlay, stderr: stderr, stdout: stdout, ctx: ctx}
protected := []string{input.GlossaryPath}
for _, source := range selected.Result.Sources() {
if source.Path != "" {
protected = append(protected, source.Path)
var loadErr *ck.LoadError
if errors.As(err, &loadErr) {
_, explanation := ckconfig.AdaptDiagnostics("Application configuration:\n", loadErr.Sources(), loadErr.Diagnostics())
if ckconfig.ClassifyConfigurationError(err) == commandkit.OutcomeUsage {
return commandkit.Usage(loadErr.Error(), explanation.Details...).WithCause(err)
}
return commandkit.Failure(loadErr.Error(), explanation.Details...).WithCause(err)
}
if inv.Context.Err() != nil || llm.IsAssetError(err) {
return commandkit.Failure("Could not prepare processing.").WithCause(err)
}
return commandkit.Usage(err.Error()).WithCause(err)
}
protected = append(protected, runtime.SourcePaths...)
session, err := diagnostics.PrepareOutput(diagnostics.OutputSelection{InputTranscriptPath: input.TranscriptPath, TranscriptPath: input.OutputPath,
ReportDir: reportDir, ReportingEnabled: cfg.Reporting.Enabled, ProtectedPaths: protected})
prepared, err := prepareProcess(inv.Context, input, loaded, inv.Reporter().Output())
if err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", llm.RedactError(err, cfg))
return 2
var selection *preflight.SelectionError
if inv.Context.Err() == nil && errors.As(err, &selection) {
return commandkit.Usage(err.Error()).WithCause(err)
}
return commandkit.Failure(err.Error()).WithCause(err)
}
state.session = session
initial := state.snapshot(reporting.StatusInProgress, nil, nil)
initialBundle, err := state.bundle(initial)
if err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", llm.RedactError(err, cfg))
return 1
defer prepared.Prepared.Output.Close()
var warningsMu sync.Mutex
warn := func(err error) {
if err == nil {
return
}
warningsMu.Lock()
prepared.Prepared.Warnings = append(prepared.Prepared.Warnings, err)
warningsMu.Unlock()
}
initFailure := []processreport.RunFailure{{Phase: "initialization", Reason: outcomes.ReasonInternalFailure}}
failedInit, err := state.bundle(state.snapshot(reporting.StatusFailed, nil, initFailure))
if err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", llm.RedactError(err, cfg))
return 1
debug := prepared.Prepared.Debug
if debug != nil {
warn(debug.WriteSourceTranscript(loaded.Source, loaded.RawTranscript))
}
if err := session.Initialize(initialBundle, failedInit); err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", llm.RedactError(err, cfg))
return 1
}
state.startDebug()
return state.execute()
}
type processState struct {
cfg config.Config
runtime *llm.Runtime
specs []contracts.ModuleRunSpec
runID string
started time.Time
transcriptPath string
glossaryPath string
outputPath string
selected selectedConfig
overlay string
ctx context.Context
stdout io.Writer
stderr io.Writer
session *diagnostics.OutputSession
debugDir *diagnostics.RunDirectory
debugWarnings []string
debugMu sync.Mutex
runOutput *runner.RunOutput
}
func generateRunID() (string, error) {
var random [12]byte
if _, err := rand.Read(random[:]); err != nil {
return "", err
}
return "run-" + hex.EncodeToString(random[:]), nil
}
func (s *processState) snapshot(status string, completed *time.Time, failures []processreport.RunFailure) reporting.Snapshot {
return processreport.Build(processreport.BuildInput{RunID: s.runID, Status: status, StartedAt: s.started,
CompletedAt: completed, TranscriptPath: s.transcriptPath, GlossaryPath: s.glossaryPath,
OutputPath: s.outputPath, ModuleSpecs: s.specs, RunOutput: s.runOutput, RunFailures: failures})
}
func (s *processState) bundle(snapshot reporting.Snapshot) (diagnostics.ReportBundle, error) {
if !s.cfg.Reporting.Enabled {
return diagnostics.ReportBundle{}, nil
}
secrets := llm.ConfiguredSecrets(&s.cfg)
errorsYAML, err := reporting.YAML(snapshot.ErrorsDocument(), secrets...)
if err != nil {
return diagnostics.ReportBundle{}, err
}
recoveriesYAML, err := reporting.YAML(snapshot.RecoveriesDocument(), secrets...)
if err != nil {
return diagnostics.ReportBundle{}, err
}
return diagnostics.ReportBundle{Errors: errorsYAML, Recoveries: recoveriesYAML,
Markdown: reporting.Markdown(snapshot, secrets...)}, nil
}
func (s *processState) debugWrite(label string, write func(*diagnostics.RunDirectory) error) {
if s.debugDir == nil {
return
}
if err := write(s.debugDir); err != nil {
s.reportDiagnosticError(fmt.Errorf("%s: %w", label, err))
}
}
func (s *processState) startDebug() {
if !s.cfg.Diagnostics.Debug {
return
}
dir, err := diagnostics.NewRunDirectory(s.cfg.Diagnostics.WorkDir, s.runID, llm.ConfiguredSecrets(&s.cfg)...)
if err != nil {
s.reportDiagnosticError(fmt.Errorf("directory: %w", err))
return
}
s.debugDir = dir
s.debugWrite("invocation", func(d *diagnostics.RunDirectory) error {
return d.WriteInvocationMetadata(diagnostics.InvocationMetadata{
Operation: "process", TranscriptPath: s.transcriptPath, GlossaryPath: s.glossaryPath,
OutputPath: s.outputPath, ConfigPath: s.selected.Path, ConfigSource: s.selected.Source,
Overlay: s.overlay, ConfigVersion: &s.cfg.Version, TranscriptDescription: s.cfg.Context.Description,
Modules: append([]string(nil), s.cfg.Pipeline.Modules...), RunID: s.runID, StartedAt: s.started,
})
loaded.RawTranscript = nil
cfg := &loaded.Configuration.Config
normalizer := normalization.NewNormalizer(normalization.NormalizationConfig{
MaxSegmentGap: cfg.Normalization.MaxSegmentGap, EllipsisGap: cfg.Normalization.EllipsisGap,
MaxSegmentDuration: cfg.Normalization.MaxSegmentDuration, MaxSegmentTokens: cfg.Normalization.MaxSegmentTokens,
})
var effective bytes.Buffer
if err := s.selected.Result.WriteEffective(&effective); err == nil {
s.debugWrite("effective settings", func(d *diagnostics.RunDirectory) error { return d.WriteEffectiveConfig(effective.Bytes()) })
} else {
s.reportDiagnosticError(fmt.Errorf("effective settings: %w", err))
transcript := loaded.Source.Canonical()
loaded.Source = nil
normalized, summary := normalizer.Normalize(transcript)
if debug != nil {
warn(debug.WriteNormalizedTranscript(normalized))
warn(debug.WriteNormalizationSummary(summary))
}
if origins, err := llm.ExplanationYAML(s.selected.Result); err == nil {
s.debugWrite("configuration origins", func(d *diagnostics.RunDirectory) error {
return d.WriteYAMLArtifact(diagnostics.ArtifactConfigOrigins, origins)
})
} else {
s.reportDiagnosticError(fmt.Errorf("configuration origins: %w", err))
if err := inv.Context.Err(); err != nil {
return finishProcess(inv, input, prepared, reporting.Snapshot{}, nil, &runner.ExecutionFailure{Phase: "normalization", Cause: err})
}
if profiles, err := s.runtime.SelectedProfilesYAML(); err == nil {
s.debugWrite("selected profiles", func(d *diagnostics.RunDirectory) error {
return d.WriteYAMLArtifact(diagnostics.ArtifactSelectedProfiles, profiles)
})
} else {
s.reportDiagnosticError(fmt.Errorf("selected profiles: %w", err))
reporter := inv.Reporter()
result, runErr := executePipeline(inv.Context, loaded, prepared, normalized, warn, func(message string) {
_ = reporter.Progress(message)
})
if runErr != nil {
return finishProcess(inv, input, prepared, result.Snapshot, nil, runErr)
}
encoder, err := outputschema.Resolve(cfg.Output.Schema)
if err != nil {
return finishProcess(inv, input, prepared, result.Snapshot, nil, &runner.ExecutionFailure{Phase: "encoding", Cause: err})
}
if result.Transcript == nil {
return finishProcess(inv, input, prepared, result.Snapshot, nil, &runner.ExecutionFailure{Phase: "encoding", Cause: fmt.Errorf("processing returned no transcript")})
}
payload, err := encoder.Encoder(result.Transcript)
if err != nil {
return finishProcess(inv, input, prepared, result.Snapshot, nil, &runner.ExecutionFailure{Phase: "encoding", Cause: err})
}
return finishProcess(inv, input, prepared, result.Snapshot, payload, nil)
}
func (s *processState) debugPath() string {
if s.debugDir == nil {
// DebugPath returns the retained artifact directory, if its preparation succeeded.
func (p *preparedProcess) DebugPath() string {
if p == nil || p.Prepared == nil || p.Prepared.Debug == nil {
return ""
}
return s.debugDir.Path()
}
func (s *processState) execute() int {
transcriptBytes, err := coreio.ReadRequiredFile(s.transcriptPath, "transcript")
if err != nil {
return s.fail("input", outcomes.ReasonInternalFailure, err)
}
glossaryBytes, err := coreio.ReadRequiredFile(s.glossaryPath, "glossary")
if err != nil {
return s.fail("input", outcomes.ReasonInternalFailure, err)
}
source, err := schema.ParseSourceTranscriptJSON(transcriptBytes)
if err != nil {
return s.fail("input", outcomes.ReasonInputInvalid, err)
}
glossary, err := schema.ParseGlossaryYAML(glossaryBytes)
if err != nil {
return s.fail("input", outcomes.ReasonInputInvalid, err)
}
s.debugWrite("source transcript", func(d *diagnostics.RunDirectory) error { return d.WriteSourceTranscript(source, transcriptBytes) })
normalizer := normalization.NewNormalizer(normalization.NormalizationConfig{
MaxSegmentGap: s.cfg.Normalization.MaxSegmentGap, EllipsisGap: s.cfg.Normalization.EllipsisGap,
MaxSegmentDuration: s.cfg.Normalization.MaxSegmentDuration, MaxSegmentTokens: s.cfg.Normalization.MaxSegmentTokens,
})
normalized, normSummary := normalizer.Normalize(sourceToCanonicalTranscript(source))
s.debugWrite("normalized transcript", func(d *diagnostics.RunDirectory) error { return d.WriteNormalizedTranscript(normalized) })
s.debugWrite("normalization summary", func(d *diagnostics.RunDirectory) error { return d.WriteNormalizationSummary(normSummary) })
if err := s.ctx.Err(); err != nil {
return s.fail("processing", outcomes.ReasonCanceled, err)
}
observations := llm.NewObservationCollector()
proposalClient, err := s.runtime.NewRoleClient("proposal", observations.Hooks())
if err != nil {
return s.fail("processing", outcomes.ReasonSetupFailure, err)
}
validationClient, err := s.runtime.NewRoleClient("validation", observations.Hooks())
if err != nil {
return s.fail("processing", outcomes.ReasonSetupFailure, err)
}
factory := modules.NewFactory(modules.Dependencies{Config: &s.cfg, Glossary: glossary, DiagnosticsDir: s.debugPath()})
result, runErr := runner.New(factory).Run(s.ctx, runner.RunInput{
Config: &s.cfg, Transcript: normalized, Glossary: glossary, ModuleSpecs: s.specs,
ProposalLLMClient: proposalClient, ProposalDiagnosticsDir: s.debugPath(),
ValidationLLMClient: validationClient, ValidationDiagnosticsDir: s.debugPath(),
CaptureCandidates: s.debugDir != nil,
ReportDiagnosticError: s.reportDiagnosticError,
})
result.Observations = observations.Snapshot()
result.ObservationsAvailable = true
result.LLMSummary = llm.Summarize(result.Observations)
s.runOutput = &result
s.writeExecutionEvidence()
if len(result.Sections) > 0 || runErr == nil {
s.writeChunkSummary(result.Sections)
}
if runErr != nil {
return s.fail("processing", fatalReason(s.ctx, runErr), runErr)
}
encoder, err := outputschema.Resolve(s.cfg.Output.Schema)
if err != nil {
return s.fail("encoding", outcomes.ReasonSetupFailure, err)
}
outputBytes, err := encoder.Encoder(result.FinalTranscript)
if err != nil {
return s.fail("encoding", outcomes.ReasonInternalFailure, err)
}
return s.finish(outputBytes)
}
func (s *processState) writeChunkSummary(inventory []contracts.SectionMetadata) {
if s.debugDir == nil {
return
}
sections := make([]chunking.Section, len(inventory))
for i, metadata := range inventory {
sections[i] = chunking.Section{Index: metadata.Index, StartSegmentID: metadata.StartSegmentID,
EndSegmentID: metadata.EndSegmentID, EstimatedTokens: metadata.EstimatedTokens,
Segments: make([]schema.Segment, metadata.SegmentCount)}
}
config := chunking.ChunkingConfig{TargetSections: s.cfg.Chunking.TargetSections,
MaxSectionTokens: s.cfg.Chunking.MaxSectionTokens, MinSectionTokens: s.cfg.Chunking.MinSectionTokens}
summary := chunking.ComputeDetailedSummary(sections, config)
s.debugWrite("chunking summary", func(d *diagnostics.RunDirectory) error { return d.WriteChunkingSummary(&summary) })
}
func (s *processState) writeExecutionEvidence() {
if s.debugDir == nil || s.runOutput == nil {
return
}
output := s.runOutput
s.debugWrite("model execution", func(d *diagnostics.RunDirectory) error {
return d.WriteJSONArtifact(diagnostics.ArtifactLLMExecution, processreport.BuildLLMExecution(output.Observations))
})
s.debugWrite("utilization", func(d *diagnostics.RunDirectory) error {
return d.WriteJSONArtifact(diagnostics.ArtifactUtilizationSummary, processreport.BuildUtilization(output, s.cfg.Backends))
})
s.debugWrite("correction ledger", func(d *diagnostics.RunDirectory) error {
return d.WriteJSONArtifact(diagnostics.ArtifactCorrectionLedger, processreport.BuildCorrectionLedger(processreport.CorrectionLedgerInput{
RunDirectoryPath: d.Path(), RunOutput: output}))
})
}
func fatalReason(ctx context.Context, err error) outcomes.ReasonCode {
if ctx.Err() != nil || errors.Is(err, context.Canceled) {
return outcomes.ReasonCanceled
}
var failure *structuredoutput.Failure
if errors.As(err, &failure) && failure.Reason != "" {
return failure.Reason
}
return outcomes.ReasonInternalFailure
}
func (s *processState) fail(phase string, reason outcomes.ReasonCode, cause error) int {
s.debugWrite("error log", func(d *diagnostics.RunDirectory) error {
return d.WriteErrorLog(phase + ": " + llm.RedactError(cause, s.cfg))
})
failures := []processreport.RunFailure{{Phase: phase, Reason: reason}}
completed := time.Now().UTC()
base, err := s.bundle(s.snapshot(reporting.StatusFailed, &completed, failures))
if err != nil {
fmt.Fprintf(s.stderr, "audita process: %s\n", llm.RedactError(err, s.cfg))
}
writeFailures := s.session.Finalize(nil, base, func(extra []diagnostics.FileFailure) diagnostics.ReportBundle {
all := append(append([]processreport.RunFailure(nil), failures...), mapWriteFailures(extra)...)
bundle, renderErr := s.bundle(s.snapshot(reporting.StatusFailed, &completed, all))
if renderErr != nil {
return base
}
return bundle
})
fmt.Fprintf(s.stderr, "audita process: %s\n", llm.RedactError(cause, s.cfg))
s.printFailures(writeFailures)
s.printDebugWarnings()
if s.debugDir != nil {
fmt.Fprintf(s.stderr, "audita process: diagnostics: %s\n", s.safePath(s.debugDir.Path()))
}
return 1
}
func (s *processState) finish(outputBytes []byte) int {
completed := time.Now().UTC()
snapshot := s.snapshot(reporting.StatusCompleted, &completed, nil)
complete, err := s.bundle(snapshot)
if err != nil {
return s.fail("report_write", outcomes.ReasonInternalFailure, err)
}
if s.session.TranscriptPath() == "" {
if _, err := s.stdout.Write(outputBytes); err != nil {
return s.fail("transcript_write", outcomes.ReasonInternalFailure, err)
}
outputBytes = nil
}
writeFailures := s.session.Finalize(outputBytes, complete, func(extra []diagnostics.FileFailure) diagnostics.ReportBundle {
failed, renderErr := s.bundle(s.snapshot(reporting.StatusFailed, &completed, mapWriteFailures(extra)))
if renderErr != nil {
return diagnostics.ReportBundle{}
}
return failed
})
if len(writeFailures) > 0 {
s.printFailures(writeFailures)
s.printDebugWarnings()
if s.debugDir != nil {
fmt.Fprintf(s.stderr, "audita process: diagnostics: %s\n", s.safePath(s.debugDir.Path()))
}
return 1
}
fmt.Fprintln(s.stderr, reporting.CompletionLine(snapshot))
for _, path := range s.session.ReportPaths() {
fmt.Fprintf(s.stderr, "Report: %s\n", s.safePath(path))
}
if s.debugDir != nil {
fmt.Fprintf(s.stderr, "Debug: %s\n", s.safePath(s.debugDir.Path()))
}
s.printDebugWarnings()
return 0
}
func mapWriteFailures(failures []diagnostics.FileFailure) []processreport.RunFailure {
out := make([]processreport.RunFailure, len(failures))
for i, failure := range failures {
phase := "report_write"
if failure.Kind == "transcript write" {
phase = "transcript_write"
}
out[i] = processreport.RunFailure{Phase: phase, Reason: outcomes.ReasonInternalFailure, OutputPath: failure.Path}
}
return out
}
func (s *processState) printFailures(failures []diagnostics.FileFailure) {
for _, failure := range failures {
fmt.Fprintf(s.stderr, "audita process: %s\n", llm.RedactError(failure, s.cfg))
}
}
func (s *processState) printDebugWarnings() {
s.debugMu.Lock()
defer s.debugMu.Unlock()
for _, warning := range s.debugWarnings {
fmt.Fprintf(s.stderr, "audita process: %s\n", warning)
}
}
// safePath sanitizes presentation only; filesystem destinations remain literal.
func (s *processState) safePath(path string) string {
return redaction.New(llm.ConfiguredSecrets(&s.cfg)).String(path)
}
func (s *processState) reportDiagnosticError(err error) {
if err == nil {
return
}
message := "debug " + llm.RedactError(err, s.cfg)
s.debugMu.Lock()
defer s.debugMu.Unlock()
s.debugWarnings = append(s.debugWarnings, message)
return p.Prepared.Debug.Path()
}

View File

@@ -0,0 +1,118 @@
package cli
import (
"fmt"
"strconv"
commandkit "go.maximumdirect.net/commandkit"
ck "go.maximumdirect.net/configkit"
)
type processInput struct {
Config commandkit.Supplied[string]
Overlay commandkit.Supplied[string]
Transcript string
Output commandkit.Supplied[string]
Debug commandkit.Supplied[bool]
Overrides []ck.Override
}
func processCommand() commandkit.Command {
stringValue := func(s string) (string, error) { return s, nil }
flags := []commandkit.Flag[processInput]{
commandkit.ValueFlag(commandkit.FlagMeta{Name: "config", Usage: "Application configuration file."}, (*string)(nil), stringValue, func(in *processInput, v commandkit.Supplied[string]) { in.Config = v }),
commandkit.ValueFlag(commandkit.FlagMeta{Name: "overlay", Usage: "Configuration overlay."}, (*string)(nil), stringValue, func(in *processInput, v commandkit.Supplied[string]) { in.Overlay = v }),
commandkit.ValueFlag(commandkit.FlagMeta{Name: "output", Usage: "Transcript output file."}, (*string)(nil), stringValue, func(in *processInput, v commandkit.Supplied[string]) { in.Output = v }),
commandkit.BoolFlag(commandkit.FlagMeta{Name: "debug", Usage: "Capture diagnostic artifacts."}, false, func(in *processInput, v commandkit.Supplied[bool]) { in.Debug = v }),
}
for _, item := range []struct {
name string
path ck.Path
}{
{"proposal-profile", ck.Keys("llm", "proposal_profile")}, {"validation-profile", ck.Keys("llm", "validation_profile")},
{"output-schema", ck.Keys("output", "schema")}, {"transcript-description", ck.Keys("context", "description")},
{"report-dir", ck.Keys("reporting", "stdout_dir")}, {"work-dir", ck.Keys("diagnostics", "work_dir")},
} {
name, path := item.name, item.path
flags = append(flags, commandkit.ValueFlag(commandkit.FlagMeta{Name: name, Usage: "Override application setting."}, (*string)(nil), stringValue,
func(in *processInput, v commandkit.Supplied[string]) {
if v.Set {
in.Overrides = append(in.Overrides, ck.Override{Path: path, Value: v.Value, Flag: "--" + name})
}
}))
}
for _, item := range []struct {
name string
path ck.Path
}{
{"validation-max-prompt-tokens", ck.Keys("validation", "max_prompt_tokens")}, {"target-sections", ck.Keys("chunking", "target_sections")},
{"max-section-tokens", ck.Keys("chunking", "max_section_tokens")}, {"min-section-tokens", ck.Keys("chunking", "min_section_tokens")},
{"normalize-max-segment-tokens", ck.Keys("normalization", "max_segment_tokens")},
} {
name, path := item.name, item.path
flags = append(flags, commandkit.ValueFlag(commandkit.FlagMeta{Name: name, Usage: "Override application setting."}, (*int)(nil), strconv.Atoi,
func(in *processInput, v commandkit.Supplied[int]) {
if v.Set {
in.Overrides = append(in.Overrides, ck.Override{Path: path, Value: v.Value, Flag: "--" + name})
}
}))
}
for _, item := range []struct {
name string
path ck.Path
}{
{"normalize-max-segment-gap", ck.Keys("normalization", "max_segment_gap")}, {"normalize-ellipsis-gap", ck.Keys("normalization", "ellipsis_gap")},
{"normalize-max-segment-duration", ck.Keys("normalization", "max_segment_duration")},
} {
name, path := item.name, item.path
flags = append(flags, commandkit.ValueFlag(commandkit.FlagMeta{Name: name, Usage: "Override application setting."}, (*float64)(nil), func(s string) (float64, error) { return strconv.ParseFloat(s, 64) },
func(in *processInput, v commandkit.Supplied[float64]) {
if v.Set {
in.Overrides = append(in.Overrides, ck.Override{Path: path, Value: v.Value, Flag: "--" + name})
}
}))
}
for _, item := range []struct {
name string
path ck.Path
}{
{"glossaries", ck.Keys("glossaries")}, {"protected-terms", ck.Keys("protected_terms")},
} {
name, path := item.name, item.path
flags = append(flags, commandkit.ValueFlag(commandkit.FlagMeta{Name: name, Usage: "JSON array of collection names, or null."}, (*any)(nil), parseCollectionNames,
func(in *processInput, value commandkit.Supplied[any]) {
if value.Set {
in.Overrides = append(in.Overrides, ck.Override{Path: path, Value: value.Value, Flag: "--" + name})
}
}))
}
flags = append(flags, commandkit.BoolFlag(commandkit.FlagMeta{Name: "reporting", Usage: "Enable ordinary reports."}, false,
func(in *processInput, v commandkit.Supplied[bool]) {
if v.Set {
in.Overrides = append(in.Overrides, ck.Override{Path: ck.Keys("reporting", "enabled"), Value: v.Value, Flag: "--reporting"})
}
}))
return commandkit.NewCommand(commandkit.CommandSpec[processInput]{Name: "process", Summary: "Polish a transcript.", Flags: flags, Run: runProcess,
Arguments: []commandkit.Argument[processInput]{commandkit.ValueArgument(commandkit.ArgumentMeta{Name: "transcript", Usage: "Transcript JSON file."}, true, stringValue, func(in *processInput, v commandkit.Supplied[string]) { in.Transcript = v.Value })},
})
}
func parseCollectionNames(raw string) (any, error) {
value, err := commandkit.ParseCLIJSON(raw)
if err != nil {
return nil, err
}
if value == nil {
return nil, nil
}
names, ok := value.([]any)
if !ok {
return nil, fmt.Errorf("expected a JSON array of collection names or null")
}
for _, name := range names {
if _, ok := name.(string); !ok {
return nil, fmt.Errorf("collection names must be strings")
}
}
return names, nil
}

View File

@@ -0,0 +1,157 @@
package cli
import (
"bytes"
"context"
"errors"
"os"
"path/filepath"
"strings"
"testing"
commandkit "go.maximumdirect.net/commandkit"
ck "go.maximumdirect.net/configkit"
)
func TestProcessShowsConfigurationLoadDiagnostics(t *testing.T) {
app, err := buildApplication()
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
name, config, finding string
}{
{"obsolete version", "version: 2\n", "docs/migrations/v3.md"},
{"invalid retry budget", "version: 3\nllm: {transient_retries: -1}\n", "retry budget must be non-negative"},
} {
t.Run(tc.name, func(t *testing.T) {
dir := t.TempDir()
configPath := filepath.Join(dir, "config.yml")
if err := os.WriteFile(configPath, []byte(tc.config), 0600); err != nil {
t.Fatal(err)
}
output := filepath.Join(dir, "out.json")
var out, stderr bytes.Buffer
args := []string{"process", "--quiet", "--config", configPath, "--output", output, filepath.Join(dir, "transcript.json")}
result := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &stderr})
var loadErr *ck.LoadError
if result.Status != 2 || !errors.As(result.Cause, &loadErr) || out.Len() != 0 ||
!strings.Contains(stderr.String(), tc.finding) || !strings.Contains(stderr.String(), configPath) {
t.Fatalf("status=%d cause=%v out=%q err=%q", result.Status, result.Cause, out.String(), stderr.String())
}
entries, err := os.ReadDir(dir)
if err != nil || len(entries) != 1 {
t.Fatalf("outputs created on load failure: %v, err=%v", entries, err)
}
})
}
}
func TestProcessUsesResolvedReportingMode(t *testing.T) {
dir := t.TempDir()
for name, contents := range map[string]string{
"config.yml": "version: 3\npipeline:\n stages: []\nreporting:\n enabled: false\n",
"transcript.json": `[{"speaker":"Alice","start":0,"end":1,"text":"hello"}]`,
"blocked": "file",
} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(contents), 0644); err != nil {
t.Fatal(err)
}
}
app, err := buildApplication()
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
name string
flags []string
status int
stdout bool
info bool
warning bool
}{
{"ordinary", nil, 0, true, false, false},
{"verbose", []string{"--verbose"}, 0, true, true, false},
{"quiet stdout", []string{"--quiet"}, 2, false, false, false},
{"quiet file", []string{"--quiet", "--output", filepath.Join(dir, "quiet.json")}, 0, false, false, false},
{"verbose after quiet", []string{"--quiet", "--verbose"}, 0, true, true, false},
{"quiet after verbose", []string{"--verbose", "--quiet", "--output", filepath.Join(dir, "ordered.json")}, 0, false, false, false},
{"debug disabled", []string{"--debug=false", "--work-dir", filepath.Join(dir, "blocked")}, 0, true, false, false},
{"debug failure", []string{"--debug", "--work-dir", filepath.Join(dir, "blocked")}, 0, true, true, true},
{"debug quiet", []string{"--debug", "--quiet", "--output", filepath.Join(dir, "debug-quiet.json"), "--work-dir", filepath.Join(dir, "blocked")}, 0, false, false, false},
} {
t.Run(tc.name, func(t *testing.T) {
var out, stderr bytes.Buffer
args := []string{"process", "--config", filepath.Join(dir, "config.yml")}
args = append(args, tc.flags...)
args = append(args, filepath.Join(dir, "transcript.json"))
result := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &stderr})
if result.Status != tc.status || (out.Len() > 0) != tc.stdout || strings.Contains(stderr.String(), "Completed:") != tc.info || strings.Contains(stderr.String(), "Debug artifact:") != tc.warning {
t.Fatalf("status=%d out=%q err=%q", result.Status, out.String(), stderr.String())
}
})
}
}
func TestProcessChecksOnlyTheActiveReportDirectory(t *testing.T) {
for _, tc := range []struct {
name string
flags []string
wantReport bool
wantError bool
}{
{"file output ignores blank configured directory", nil, true, false},
{"explicit blank directory", []string{"--report-dir="}, false, true},
{"disabled reporting ignores explicit blank directory", []string{"--reporting=false", "--report-dir="}, false, false},
} {
t.Run(tc.name, func(t *testing.T) {
dir := t.TempDir()
configPath := filepath.Join(dir, "config.yml")
if err := os.WriteFile(configPath, []byte("version: 3\npipeline: {stages: []}\nreporting: {stdout_dir: ''}\n"), 0600); err != nil {
t.Fatal(err)
}
transcript := filepath.Join(dir, "transcript.json")
if err := os.WriteFile(transcript, []byte(`[{"speaker":"Alice","start":0,"end":1,"text":"hello"}]`), 0600); err != nil {
t.Fatal(err)
}
output := filepath.Join(dir, "output.json")
args := append([]string{"process", "--config", configPath, "--output", output}, tc.flags...)
var stdout, stderr bytes.Buffer
status := Run(context.Background(), append(args, transcript), &stdout, &stderr)
if (status != 0) != tc.wantError || (tc.wantError && !strings.Contains(stderr.String(), "report directory is required")) {
t.Fatalf("status=%d stdout=%q stderr=%q", status, stdout.String(), stderr.String())
}
_, err := os.Stat(filepath.Join(dir, "errors.yml"))
if (tc.wantReport && err != nil) || (!tc.wantReport && !os.IsNotExist(err)) {
t.Fatalf("report file: %v, want present=%t", err, tc.wantReport)
}
})
}
}
func TestProcessCollectionFlags(t *testing.T) {
dir := t.TempDir()
for name, contents := range map[string]string{
"config.yml": "version: 3\npipeline:\n stages: []\nreporting:\n enabled: false\nglossary_collections:\n party: {entries: []}\n",
"transcript.json": `[{"speaker":"Alice","start":0,"end":1,"text":"hello"}]`,
} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(contents), 0644); err != nil {
t.Fatal(err)
}
}
app, err := buildApplication()
if err != nil {
t.Fatal(err)
}
for _, tc := range []struct {
value string
status int
}{{`["party"]`, 0}, {`[]`, 0}, {`null`, 0}, {`[1]`, 2}, {`"party"`, 2}} {
var out, stderr bytes.Buffer
args := []string{"process", "--config", filepath.Join(dir, "config.yml"), "--glossaries", tc.value, filepath.Join(dir, "transcript.json")}
outcome := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &stderr})
if outcome.Status != tc.status {
t.Fatalf("value=%q status=%d out=%q err=%q", tc.value, outcome.Status, out.String(), stderr.String())
}
}
}

View File

@@ -0,0 +1,179 @@
package cli
import (
"bytes"
"context"
"crypto/rand"
"encoding/hex"
"errors"
"fmt"
"io"
"path/filepath"
"time"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/config"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/diagnostics"
coreio "gitea.maximumdirect.net/eric/audita/v4/internal/core/io"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/reporting"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/llm"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/preflight"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/processreport"
"go.maximumdirect.net/ckconfig"
commandkit "go.maximumdirect.net/commandkit"
ck "go.maximumdirect.net/configkit"
pk "go.maximumdirect.net/promptkit"
)
type processInputs struct {
Configuration *ck.Result[config.Config]
Runtime *llm.Runtime
Source *schema.SourceTranscript
RawTranscript []byte
ProtectedPaths []string
}
func loadProcessInputs(ctx context.Context, input processInput, mode commandkit.ReportingMode) (*processInputs, error) {
if mode == commandkit.ReportingModeQuiet && input.Output.Value == "" {
return nil, fmt.Errorf("quiet processing requires an output file or /dev/null")
}
selection := ckconfig.Selection{Config: input.Config, Overlay: input.Overlay, Overrides: input.Overrides}
loaded, err := loadApplication(ctx, selection, struct{}{}, nil)
if err != nil {
return nil, err
}
runtime, err := llm.NewRuntime(ctx, loaded, nil)
if err != nil {
return nil, err
}
if err := ctx.Err(); err != nil {
return nil, err
}
raw, err := coreio.ReadRequiredFile(input.Transcript, "transcript")
if ctx.Err() != nil {
return nil, errors.Join(err, ctx.Err())
}
if err != nil {
return nil, err
}
source, err := schema.ParseSourceTranscriptJSON(raw)
if err != nil {
return nil, err
}
if !input.Debug.Value {
raw = nil
}
protected := append([]string(nil), runtime.SourcePaths...)
for _, entry := range loaded.Sources() {
if entry.Kind == ck.SourceKindFile && entry.Path != "" {
protected = append(protected, entry.Path)
}
}
return &processInputs{Configuration: loaded, Runtime: runtime, Source: source, RawTranscript: raw, ProtectedPaths: protected}, nil
}
// preparedProcess groups the output resources and the facts needed for reports.
type preparedProcess struct {
Prepared *preflight.Prepared
RunID string
Started time.Time
}
func prepareProcess(ctx context.Context, input processInput, loaded *processInputs, stdout io.Writer) (*preparedProcess, error) {
cfg := &loaded.Configuration.Config
reportDir := ""
reportDirSet := false
for _, override := range input.Overrides {
if override.Path.String() == "/reporting/stdout_dir" {
reportDirSet = true
}
}
if cfg.Reporting.Enabled {
reportDir = cfg.Reporting.StdoutDir
if input.Output.Value != "" && !reportDirSet {
reportDir, _ = filepath.Split(input.Output.Value)
if reportDir == "" {
reportDir = "."
}
}
}
runID, err := generateRunID()
if err != nil {
return nil, err
}
started := time.Now().UTC()
var initial diagnostics.ReportBundle
var failed diagnostics.ReportRenderer
if cfg.Reporting.Enabled {
snapshot := reporting.Snapshot{RunID: runID, Status: reporting.StatusInProgress, StartedAt: started, TranscriptPath: input.Transcript, OutputPath: input.Output.Value}
for index, item := range cfg.Pipeline.Stages {
snapshot.StageNames = append(snapshot.StageNames, reporting.StageLabel(index, item.Module, item.ID))
}
initial, err = renderReportBundle(snapshot)
if err != nil {
return nil, err
}
failed = func(primary error, failures []diagnostics.FileFailure) (diagnostics.ReportBundle, error) {
failedSnapshot := snapshot
completed := time.Now().UTC()
failedSnapshot.CompletedAt = &completed
return renderReportBundle(processreport.Failed(failedSnapshot, primary, "initialization", failures))
}
}
var debug *preflight.DebugInput
var warnings []error
if input.Debug.Value {
var effective bytes.Buffer
if err := loaded.Configuration.WriteEffective(&effective); err != nil {
warnings = append(warnings, err)
}
debug = &preflight.DebugInput{WorkDir: cfg.Diagnostics.WorkDir, RunID: runID, EffectiveConfig: effective.Bytes(), Metadata: diagnostics.InvocationMetadata{Operation: "process", TranscriptPath: input.Transcript, OutputPath: input.Output.Value, Overlay: input.Overlay.Value, ConfigVersion: &cfg.Version, RunID: runID, StartedAt: started}}
}
checkedBackends := make(map[string]struct{})
prepared, err := preflight.Prepare(ctx, preflight.Input{InspectProfile: func(ctx context.Context, id string) error {
profile, err := loaded.Runtime.Engine.InspectProfile(ctx, id)
if errors.Is(err, pk.ErrProfileNotFound) {
return &preflight.SelectionError{Cause: err}
}
if err != nil || profile.Backend == nil {
return err
}
backend := *profile.Backend
if _, ok := checkedBackends[backend]; ok {
return nil
}
_, err = loaded.Runtime.Engine.InspectBackend(ctx, backend)
if errors.Is(err, pk.ErrBackendNotFound) {
return &preflight.SelectionError{Cause: err}
}
if err == nil {
checkedBackends[backend] = struct{}{}
}
return err
}, Config: cfg, Transcript: loaded.Source, Output: diagnostics.OutputSelection{InputTranscriptPath: input.Transcript, TranscriptPath: input.Output.Value, ReportDir: reportDir, ReportingEnabled: cfg.Reporting.Enabled, ProtectedPaths: loaded.ProtectedPaths, Stdout: stdout}, InitialReports: initial, FailedReports: failed, Debug: debug})
if err != nil {
return nil, err
}
prepared.Warnings = append(warnings, prepared.Warnings...)
return &preparedProcess{Prepared: prepared, RunID: runID, Started: started}, nil
}
func generateRunID() (string, error) {
var random [12]byte
if _, err := rand.Read(random[:]); err != nil {
return "", err
}
return "run-" + hex.EncodeToString(random[:]), nil
}
func renderReportBundle(value reporting.Snapshot) (diagnostics.ReportBundle, error) {
errorsYAML, err := reporting.YAML(value.ErrorsDocument())
if err != nil {
return diagnostics.ReportBundle{}, err
}
recoveriesYAML, err := reporting.YAML(value.RecoveriesDocument())
if err != nil {
return diagnostics.ReportBundle{}, err
}
return diagnostics.ReportBundle{Errors: errorsYAML, Recoveries: recoveriesYAML, Markdown: reporting.Markdown(value)}, nil
}

View File

@@ -0,0 +1,108 @@
package cli
import (
"context"
"io"
"os"
"path/filepath"
"slices"
"strings"
"testing"
commandkit "go.maximumdirect.net/commandkit"
ck "go.maximumdirect.net/configkit"
)
func TestQuietDestinationCheckPrecedesInputAcquisition(t *testing.T) {
_, err := loadProcessInputs(context.Background(), processInput{Transcript: "missing.json"}, commandkit.ReportingModeQuiet)
if err == nil || !strings.Contains(err.Error(), "/dev/null") {
t.Fatalf("error=%v", err)
}
}
func TestProcessAcquisitionCapturesConsumedFiles(t *testing.T) {
dir := t.TempDir()
for name, contents := range map[string]string{
"config.yml": "version: 3\npipeline:\n stages: []\n",
"transcript.json": `[{"speaker":"Alice","start":0,"end":1,"text":"hello"}]`,
"prompts.yml": "prompts:\n - id: extra\n messages:\n - role: user\n content_file: text.txt\n output:\n format: text\n validation_mode: none\n",
"text.txt": "example",
} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(contents), 0644); err != nil {
t.Fatal(err)
}
}
input := processInput{Config: commandkit.Supplied[string]{Value: filepath.Join(dir, "config.yml"), Set: true}, Transcript: filepath.Join(dir, "transcript.json")}
result, err := loadProcessInputs(context.Background(), input, commandkit.ReportingModeOrdinary)
if err != nil {
t.Fatal(err)
}
for _, name := range []string{"config.yml", "prompts.yml", "text.txt"} {
if !slices.Contains(result.ProtectedPaths, filepath.Join(dir, name)) {
t.Errorf("missing %s in %v", name, result.ProtectedPaths)
}
}
}
func TestPrepareProcessInitializesReportsAndToleratesDebugLoss(t *testing.T) {
dir := t.TempDir()
for name, contents := range map[string]string{
"config.yml": "version: 3\npipeline:\n stages: []\n",
"transcript.json": `[{"speaker":"Alice","start":0,"end":1,"text":"hello"}]`,
"blocked": "not a directory",
} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(contents), 0644); err != nil {
t.Fatal(err)
}
}
input := processInput{Config: commandkit.Supplied[string]{Value: filepath.Join(dir, "config.yml"), Set: true}, Transcript: filepath.Join(dir, "transcript.json"), Output: commandkit.Supplied[string]{Value: filepath.Join(dir, "output.json"), Set: true}, Debug: commandkit.Supplied[bool]{Value: true, Set: true}, Overrides: []ck.Override{{Path: ck.Keys("diagnostics", "work_dir"), Value: filepath.Join(dir, "blocked"), Flag: "--work-dir"}}}
loaded, err := loadProcessInputs(context.Background(), input, commandkit.ReportingModeOrdinary)
if err != nil {
t.Fatal(err)
}
prepared, err := prepareProcess(context.Background(), input, loaded, io.Discard)
if err != nil {
t.Fatal(err)
}
defer prepared.Prepared.Output.Close()
if len(prepared.Prepared.Warnings) == 0 {
t.Fatal("debug loss was not reported")
}
report, err := os.ReadFile(filepath.Join(dir, "errors.yml"))
if err != nil || !strings.Contains(string(report), "in_progress") {
t.Fatalf("report=%q err=%v", report, err)
}
if _, err := os.Stat(input.Output.Value); !os.IsNotExist(err) {
t.Fatalf("output published early: %v", err)
}
}
func TestCollectionFlagJSON(t *testing.T) {
for _, tc := range []struct {
raw string
valid bool
null bool
size int
}{
{`["party","spells"]`, true, false, 2}, {`[]`, true, false, 0}, {`null`, true, true, 0},
{`"party"`, false, false, 0}, {`[1]`, false, false, 0}, {`["x"] true`, false, false, 0},
} {
result, err := parseCollectionNames(tc.raw)
if (err == nil) != tc.valid {
t.Fatalf("%s error=%v", tc.raw, err)
}
if !tc.valid {
continue
}
if tc.null {
if result != nil {
t.Fatalf("null=%v", result)
}
continue
}
list, ok := result.([]any)
if !ok || len(list) != tc.size {
t.Fatalf("%s result=%v", tc.raw, result)
}
}
}

View File

@@ -0,0 +1,245 @@
package cli
import (
"bytes"
"context"
"encoding/json"
"fmt"
"io"
"net/http"
"os"
"path/filepath"
"reflect"
"strings"
"sync"
"testing"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/config"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/diagnostics"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/llm"
commandkit "go.maximumdirect.net/commandkit"
ck "go.maximumdirect.net/configkit"
)
type controlledTransport func(*http.Request) (*http.Response, error)
func (f controlledTransport) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
func TestProcessingUsesPerEntryProfilesInOrder(t *testing.T) {
var mu sync.Mutex
var models []string
var prompts []string
proposalCalls := 0
transport := controlledTransport(func(r *http.Request) (*http.Response, error) {
var request struct {
Model string `json:"model"`
Messages []struct {
Content string `json:"content"`
} `json:"messages"`
}
if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
return nil, err
}
var contents string
for _, message := range request.Messages {
contents += message.Content
}
mu.Lock()
models = append(models, request.Model)
prompts = append(prompts, contents)
if request.Model == "model-one" {
proposalCalls++
}
firstProposalCall := proposalCalls
mu.Unlock()
result := `{"validations":[{"correction_index":1,"approved":true,"reason":"ok"}]}`
switch request.Model {
case "model-one":
result = `{"corrections":[{"id":1,"original_text":"Alyce","corrected_text":"Alice"}]}`
if firstProposalCall == 1 {
result = `{"invalid":true}`
}
case "model-two":
result = `{"corrections":[{"id":1,"original_text":"Sheeld","corrected_text":"Shield"}]}`
case "model-three":
result = `{"corrections":[{"id":1,"original_text":"casts","corrected_text":"cast"}]}`
}
encoded, _ := json.Marshal(result)
body := fmt.Sprintf(`{"model":"fixture","choices":[{"message":{"role":"assistant","content":%s}}]}`, encoded)
return &http.Response{StatusCode: 200, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(body)), Request: r}, nil
})
dir := t.TempDir()
files := map[string]string{
"config.yml": `version: 3
glossary_collections:
party:
entries: [{id: alice, name: Alice, category: person}]
spells:
entries: [{id: shield, name: Shield, category: spell}]
protected_terms: [party, spells]
llm: {validation_profile: review}
pipeline:
stages:
- module: glossary
id: "party/../|<tag>"
glossaries: [party]
llm: {proposal_profile: one}
- module: glossary
id: spell
glossaries: [spells]
llm: {proposal_profile: two}
- module: grammar
glossaries: [party, spells]
llm: {proposal_profile: three}
`,
"prompts.yml": fmt.Sprintf("profiles:\n - {id: one, endpoint: %q, model: model-one, api_key_required: false}\n - {id: two, endpoint: %q, model: model-two, api_key_required: false}\n - {id: three, endpoint: %q, model: model-three, api_key_required: false}\n - {id: review, endpoint: %q, model: review, api_key_required: false}\n", "https://example.invalid/v1", "https://example.invalid/v1", "https://example.invalid/v1", "https://example.invalid/v1"),
"transcript.json": `[{"speaker":"Alice","start":0,"end":1,"text":"Alyce casts Sheeld."}]`,
}
for name, value := range files {
if err := os.WriteFile(filepath.Join(dir, name), []byte(value), 0600); err != nil {
t.Fatal(err)
}
}
loaded, err := config.Load(ck.Input{Source: ck.File(filepath.Join(dir, "config.yml"))}, "")
if err != nil {
t.Fatal(err)
}
runtime, err := llm.NewRuntime(context.Background(), loaded, &http.Client{Transport: transport})
if err != nil {
t.Fatal(err)
}
source, err := schema.ParseSourceTranscriptJSON([]byte(files["transcript.json"]))
if err != nil {
t.Fatal(err)
}
inputs := &processInputs{Configuration: loaded, Runtime: runtime, Source: source}
loaded.Config.Diagnostics.WorkDir = dir
loaded.Config.Reporting.StdoutDir = dir
prepared, err := prepareProcess(context.Background(), processInput{Transcript: filepath.Join(dir, "transcript.json"), Debug: commandkit.Supplied[bool]{Value: true}}, inputs, &bytes.Buffer{})
if err != nil {
t.Fatal(err)
}
defer prepared.Prepared.Output.Close()
result, err := executePipeline(context.Background(), inputs, prepared, source.Canonical(), func(error) {}, nil)
if err != nil {
t.Fatal(err)
}
if result.Transcript.Segments[0].Text != "Alice cast Shield." {
t.Fatalf("result=%q models=%v", result.Transcript.Segments[0].Text, models)
}
if len(prompts) > 4 && !strings.Contains(prompts[4], "Alice casts Sheeld.") {
t.Fatalf("second proposal missed earlier edit: %s", prompts[4])
}
if len(result.Snapshot.WorkUnits) != 3 || result.Snapshot.WorkUnits[0].StageID == nil || *result.Snapshot.WorkUnits[0].StageID != "party/../|<tag>" || result.Snapshot.WorkUnits[1].StageIndex != 1 || result.Snapshot.WorkUnits[2].StageID != nil {
t.Fatalf("work unit identities: %+v", result.Snapshot.WorkUnits)
}
if len(result.Snapshot.Recoveries) != 1 || result.Snapshot.Recoveries[0].StageIndex != 0 || result.Snapshot.Recoveries[0].StageID == nil || *result.Snapshot.Recoveries[0].StageID != "party/../|<tag>" {
t.Fatalf("recovery attribution: %+v", result.Snapshot.Recoveries)
}
type coordinates struct {
StageIndex int `json:"stage_index"`
StageID *string `json:"stage_id"`
}
expected := map[int]string{0: "party/../|<tag>", 1: "spell", 2: ""}
check := func(name string, entries []coordinates) {
t.Helper()
seen := make(map[int]bool)
for _, entry := range entries {
id, ok := expected[entry.StageIndex]
if !ok || (id == "" && entry.StageID != nil) || (id != "" && (entry.StageID == nil || *entry.StageID != id)) {
t.Fatalf("%s has wrong stage association: %+v", name, entry)
}
seen[entry.StageIndex] = true
}
if len(seen) != len(expected) {
t.Fatalf("%s missing stage associations: %v", name, seen)
}
}
raw, err := os.ReadFile(filepath.Join(prepared.DebugPath(), diagnostics.ArtifactCorrectionLedger))
if err != nil {
t.Fatal(err)
}
var ledger []coordinates
if err := json.Unmarshal(raw, &ledger); err != nil {
t.Fatal(err)
}
check("ledger", ledger)
raw, err = os.ReadFile(filepath.Join(prepared.DebugPath(), diagnostics.ArtifactLLMExecution))
if err != nil {
t.Fatal(err)
}
var calls struct {
Calls []struct {
Context struct {
coordinates
Role string
}
}
}
if err := json.Unmarshal(raw, &calls); err != nil {
t.Fatal(err)
}
var locations []coordinates
roles := make(map[int]map[string]bool)
for _, call := range calls.Calls {
location := call.Context.coordinates
locations = append(locations, location)
if roles[location.StageIndex] == nil {
roles[location.StageIndex] = make(map[string]bool)
}
roles[location.StageIndex][call.Context.Role] = true
}
check("LLM observations", locations)
for index := range expected {
if !roles[index]["proposal"] || !roles[index]["validation"] {
t.Fatalf("stage %d missing role evidence: %v", index, roles[index])
}
}
if !reflect.DeepEqual(models, []string{"model-one", "model-one", "review", "review", "model-two", "review", "review", "model-three", "review", "review"}) {
t.Fatalf("models=%v", models)
}
}
func TestRecoverableModelFailureKeepsNormalizedTranscript(t *testing.T) {
dir := t.TempDir()
files := map[string]string{
"config.yml": "version: 3\nllm: {proposal_profile: local, transient_retries: 0}\npipeline:\n stages: [{module: grammar, id: failing}]\n",
"prompts.yml": "profiles:\n - {id: local, endpoint: 'https://example.invalid/v1', model: fixture, api_key_required: false}\n",
"transcript.json": `[{"speaker":"Alice","start":0,"end":1,"text":"hello"}]`,
}
for name, value := range files {
if err := os.WriteFile(filepath.Join(dir, name), []byte(value), 0600); err != nil {
t.Fatal(err)
}
}
loaded, err := config.Load(ck.Input{Source: ck.File(filepath.Join(dir, "config.yml"))}, "")
if err != nil {
t.Fatal(err)
}
transport := controlledTransport(func(r *http.Request) (*http.Response, error) {
return &http.Response{StatusCode: http.StatusServiceUnavailable, Header: make(http.Header), Body: io.NopCloser(strings.NewReader(`{"error":{"message":"temporarily unavailable"}}`)), Request: r}, nil
})
runtime, err := llm.NewRuntime(context.Background(), loaded, &http.Client{Transport: transport})
if err != nil {
t.Fatal(err)
}
source, err := schema.ParseSourceTranscriptJSON([]byte(files["transcript.json"]))
if err != nil {
t.Fatal(err)
}
inputs := &processInputs{Configuration: loaded, Runtime: runtime, Source: source}
loaded.Config.Reporting.StdoutDir = dir
prepared, err := prepareProcess(context.Background(), processInput{Transcript: filepath.Join(dir, "transcript.json")}, inputs, &bytes.Buffer{})
if err != nil {
t.Fatal(err)
}
defer prepared.Prepared.Output.Close()
result, err := executePipeline(context.Background(), inputs, prepared, source.Canonical(), func(error) {}, nil)
if err != nil {
t.Fatal(err)
}
if result.Transcript.Segments[0].Text != "hello" || len(result.Snapshot.Errors) != 1 || result.Snapshot.Errors[0].Scope != "work_unit" || result.Snapshot.Errors[0].StageID == nil || *result.Snapshot.Errors[0].StageID != "failing" {
t.Fatalf("result=%+v errors=%+v", result.Transcript, result.Snapshot.Errors)
}
}

View File

@@ -0,0 +1,57 @@
package cli
import (
"errors"
"fmt"
"time"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/chunking"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/diagnostics"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/reporting"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/processreport"
commandkit "go.maximumdirect.net/commandkit"
)
// finishProcess delivers the transcript and reports before emitting success information.
func finishProcess(inv commandkit.Invocation, input processInput, prepared *preparedProcess, snapshot reporting.Snapshot, transcript []byte, primary error) commandkit.Outcome {
reporter := inv.Reporter()
for _, warning := range prepared.Prepared.Warnings {
_ = reporter.Warn("Debug artifact: " + warning.Error())
}
completed := time.Now().UTC()
snapshot.RunID, snapshot.StartedAt, snapshot.CompletedAt = prepared.RunID, prepared.Started, &completed
snapshot.TranscriptPath, snapshot.OutputPath = input.Transcript, input.Output.Value
snapshot.Status = reporting.StatusCompleted
reportPaths := prepared.Prepared.Output.ReportPaths()
var render diagnostics.ReportRenderer
if len(reportPaths) > 0 {
render = func(cause error, failures []diagnostics.FileFailure) (diagnostics.ReportBundle, error) {
report := snapshot
if cause != nil || len(failures) > 0 {
phase := "processing"
if primary == nil {
phase = "publication"
}
report = processreport.Failed(snapshot, cause, phase, failures)
}
return renderReportBundle(report)
}
}
result := prepared.Prepared.Output.Finish(inv.Context, primary, transcript, render)
if result != nil {
var infeasible *chunking.InfeasibleTargetError
var outputFailure diagnostics.FileFailure
if inv.Context.Err() == nil && errors.As(result, &infeasible) && !errors.As(result, &outputFailure) {
return commandkit.Usage(infeasible.Error()).WithCause(result)
}
return commandkit.Failure(result.Error()).WithCause(result)
}
_ = reporter.AtEnd().Info(reporting.CompletionLine(snapshot))
for _, path := range reportPaths {
_ = reporter.AtEnd().Info(fmt.Sprintf("Report: %s", path))
}
if prepared.Prepared.Debug != nil {
_ = reporter.AtEnd().Info(fmt.Sprintf("Diagnostics: %s", prepared.Prepared.Debug.Path()))
}
return commandkit.Success()
}

View File

@@ -0,0 +1,197 @@
package cli
import (
"bytes"
"context"
"errors"
"os"
"path/filepath"
"strings"
"testing"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/reporting"
commandkit "go.maximumdirect.net/commandkit"
"go.yaml.in/yaml/v4"
)
func TestPreparedDeliveryFollowsReportingMode(t *testing.T) {
dir := t.TempDir()
for name, contents := range map[string]string{
"config.yml": "version: 3\npipeline:\n stages: []\nreporting:\n enabled: false\n",
"transcript.json": `[{"speaker":"Alice","start":0,"end":1,"text":"hello"}]`,
} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(contents), 0644); err != nil {
t.Fatal(err)
}
}
for _, tc := range []struct {
name string
flags []string
file bool
wantInfo bool
}{
{"ordinary", nil, false, false}, {"verbose", []string{"--verbose"}, false, true}, {"quiet file", []string{"--quiet"}, true, false},
} {
t.Run(tc.name, func(t *testing.T) {
input := processInput{Config: commandkit.Supplied[string]{Value: filepath.Join(dir, "config.yml"), Set: true}, Transcript: filepath.Join(dir, "transcript.json")}
if tc.file {
input.Output = commandkit.Supplied[string]{Value: filepath.Join(dir, "result.json"), Set: true}
}
cmd := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "deliver", Run: func(inv commandkit.Invocation, _ struct{}) commandkit.Outcome {
loaded, err := loadProcessInputs(inv.Context, input, inv.ReportingMode())
if err != nil {
return commandkit.Usage(err.Error())
}
prepared, err := prepareProcess(inv.Context, input, loaded, inv.Reporter().Output())
if err != nil {
return commandkit.Failure(err.Error())
}
return finishProcess(inv, input, prepared, reporting.Snapshot{}, []byte("transcript bytes"), nil)
}})
app, err := commandkit.New(commandkit.Identity{Name: "test"}, cmd)
if err != nil {
t.Fatal(err)
}
var out, stderr bytes.Buffer
args := append([]string{"deliver"}, tc.flags...)
outcome := app.Execute(context.Background(), args, commandkit.Streams{Out: &out, Err: &stderr})
if outcome.Status != 0 {
t.Fatalf("outcome=%+v err=%s", outcome, stderr.String())
}
if tc.file {
data, err := os.ReadFile(input.Output.Value)
if err != nil || string(data) != "transcript bytes" {
t.Fatalf("file=%q err=%v", data, err)
}
if out.Len() != 0 {
t.Fatalf("stdout=%q", out.String())
}
} else if out.String() != "transcript bytes" {
t.Fatalf("stdout=%q", out.String())
}
if strings.Contains(stderr.String(), "Completed:") != tc.wantInfo {
t.Fatalf("stderr=%q", stderr.String())
}
})
}
}
func TestDeliveryFailureSuppressesCompletionSummary(t *testing.T) {
dir := t.TempDir()
t.Chdir(dir)
for name, contents := range map[string]string{
"config.yml": "version: 3\npipeline:\n stages: []\n",
"transcript.json": `[{"speaker":"Alice","start":0,"end":1,"text":"hello"}]`,
} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(contents), 0644); err != nil {
t.Fatal(err)
}
}
input := processInput{Config: commandkit.Supplied[string]{Value: filepath.Join(dir, "config.yml"), Set: true}, Transcript: filepath.Join(dir, "transcript.json")}
cmd := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "deliver", Run: func(inv commandkit.Invocation, _ struct{}) commandkit.Outcome {
loaded, err := loadProcessInputs(inv.Context, input, inv.ReportingMode())
if err != nil {
return commandkit.Failure(err.Error())
}
prepared, err := prepareProcess(inv.Context, input, loaded, inv.Reporter().Output())
if err != nil {
return commandkit.Failure(err.Error())
}
return finishProcess(inv, input, prepared, reporting.Snapshot{}, []byte("transcript bytes"), nil)
}})
app, err := commandkit.New(commandkit.Identity{Name: "test"}, cmd)
if err != nil {
t.Fatal(err)
}
var stderr bytes.Buffer
outcome := app.Execute(context.Background(), []string{"deliver", "--verbose"}, commandkit.Streams{Out: shortProcessWriter{}, Err: &stderr})
if outcome.Status == 0 || strings.Contains(stderr.String(), "Completed:") {
t.Fatalf("status=%d stderr=%q", outcome.Status, stderr.String())
}
var errs reporting.ErrorsDocument
var recoveries reporting.RecoveriesDocument
for path, target := range map[string]any{"errors.yml": &errs, "recoveries.yml": &recoveries} {
data, err := os.ReadFile(path)
if err != nil {
t.Fatal(err)
}
if err := yaml.Unmarshal(data, target); err != nil {
t.Fatal(err)
}
}
if errs.Status != reporting.StatusFailed || recoveries.Status != reporting.StatusFailed ||
errs.Summary.RunErrors == nil || *errs.Summary.RunErrors != 1 ||
recoveries.Summary.RunErrors == nil || *recoveries.Summary.RunErrors != 1 ||
len(errs.Errors) != 1 || errs.Errors[0].Reason != "output_failure" {
t.Fatalf("failed output reports disagree: %+v %+v", errs, recoveries)
}
}
func TestCanceledEmptyPipelineLeavesTranscriptAndFinalizesReports(t *testing.T) {
dir := t.TempDir()
for name, contents := range map[string]string{
"config.yml": "version: 3\npipeline: {stages: []}\n",
"transcript.json": `[{"speaker":"Alice","start":0,"end":1,"text":"hello"}]`,
"output.json": "previous transcript",
} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(contents), 0600); err != nil {
t.Fatal(err)
}
}
input := processInput{
Config: commandkit.Supplied[string]{Value: filepath.Join(dir, "config.yml"), Set: true},
Transcript: filepath.Join(dir, "transcript.json"),
Output: commandkit.Supplied[string]{Value: filepath.Join(dir, "output.json"), Set: true},
}
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
cmd := commandkit.NewCommand(commandkit.CommandSpec[struct{}]{Name: "deliver", Run: func(inv commandkit.Invocation, _ struct{}) commandkit.Outcome {
loaded, err := loadProcessInputs(inv.Context, input, inv.ReportingMode())
if err != nil {
t.Fatal(err)
}
prepared, err := prepareProcess(inv.Context, input, loaded, inv.Reporter().Output())
if err != nil {
t.Fatal(err)
}
defer prepared.Prepared.Output.Close()
result, err := executePipeline(inv.Context, loaded, prepared, loaded.Source.Canonical(), func(error) {}, nil)
if err != nil {
t.Fatal(err)
}
cancel()
return finishProcess(inv, input, prepared, result.Snapshot, []byte("new transcript"), nil)
}})
app, err := commandkit.New(commandkit.Identity{Name: "test"}, cmd)
if err != nil {
t.Fatal(err)
}
var stdout, stderr bytes.Buffer
outcome := app.Execute(ctx, []string{"deliver", "--verbose"}, commandkit.Streams{Out: &stdout, Err: &stderr})
if outcome.Status == 0 || !errors.Is(outcome.Cause, context.Canceled) || strings.Contains(stderr.String(), "Completed:") {
t.Fatalf("outcome=%+v stderr=%q", outcome, stderr.String())
}
if data, err := os.ReadFile(input.Output.Value); err != nil || string(data) != "previous transcript" {
t.Fatalf("transcript changed after cancellation: %q, %v", data, err)
}
var errorsDoc reporting.ErrorsDocument
var recoveries reporting.RecoveriesDocument
for name, target := range map[string]any{"errors.yml": &errorsDoc, "recoveries.yml": &recoveries} {
data, err := os.ReadFile(filepath.Join(dir, name))
if err != nil {
t.Fatal(err)
}
if err := yaml.Unmarshal(data, target); err != nil {
t.Fatal(err)
}
}
if errorsDoc.Status != reporting.StatusFailed || recoveries.Status != reporting.StatusFailed ||
len(errorsDoc.Errors) != 1 || errorsDoc.Errors[0].Reason != "canceled" {
t.Fatalf("reports did not capture cancellation: %+v %+v", errorsDoc, recoveries)
}
}
type shortProcessWriter struct{}
func (shortProcessWriter) Write(data []byte) (int, error) { return len(data) / 2, nil }

View File

@@ -0,0 +1,79 @@
package cli
import (
"context"
"fmt"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/diagnostics"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/reporting"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/llm"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/outcomes"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/processreport"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/runner"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/structuredoutput"
"gitea.maximumdirect.net/eric/audita/v4/internal/modules"
)
func executePipeline(ctx context.Context, loaded *processInputs, prepared *preparedProcess, normalized *schema.Transcript, warn func(error), progress func(string)) (processResult, error) {
cfg := &loaded.Configuration.Config
specs := prepared.Prepared.Specs
debug := prepared.Prepared.Debug
evidence := runner.EvidenceSelection{Reports: cfg.Reporting.Enabled, Debug: debug != nil}
var observer *llm.ObservationCollector
var hooks llm.CallHooks
if debug != nil {
observer = llm.NewObservationCollector()
hooks = observer.Hooks()
}
if progress != nil {
hooks.OnProgress = func(coordinates structuredoutput.DiagnosticContext, counts *outcomes.ExecutionCounts, err error) {
reportModelProgress(progress, coordinates, counts, err)
}
}
for i := range specs {
item := &specs[i]
setupFailure := func(role string, cause error) error {
return &runner.ExecutionFailure{Phase: "setup", Origin: &outcomes.Reference{
StageIndex: &item.Index, StageID: item.ID, ModuleKey: item.ModuleKey, ModuleInstance: item.InstanceName,
}, Cause: fmt.Errorf("%s %s client: %w", item.InstanceName, role, cause)}
}
proposal, err := loaded.Runtime.NewRoleClient("proposal", *item.Settings.LLM.ProposalProfile, item.Settings.LLM, hooks)
if err != nil {
return processResult{}, setupFailure("proposal", err)
}
validation, err := loaded.Runtime.NewRoleClient("validation", *item.Settings.LLM.ValidationProfile, item.Settings.LLM, hooks)
if err != nil {
return processResult{}, setupFailure("validation", err)
}
item.ProposalClient, item.ValidationClient = proposal, validation
if item.Settings.LLM.CorrectionRepairAttempts > 0 {
repair, err := loaded.Runtime.NewRoleClient("correction_repair", *item.Settings.LLM.CorrectionRepairProfile, item.Settings.LLM, hooks)
if err != nil {
return processResult{}, setupFailure("correction repair", err)
}
item.RepairCoordinator = repair
}
}
var interactions structuredoutput.InteractionSink
var writer *llm.DiagnosticsWriter
if debug != nil {
writer = llm.NewDiagnosticsWriter(debug.Path())
interactions = writer
}
output, runErr := runner.New(modules.NewFactory()).Run(ctx, runner.RunInput{
Config: cfg, Transcript: normalized, ModuleSpecs: specs,
Interactions: interactions, Evidence: &evidence, Progress: runnerProgress(progress),
})
if debug != nil {
for _, warning := range writer.Warnings() {
warn(warning)
}
observations := processreport.IndexLLMObservations(observer.Snapshot(), output.WorkUnits)
warn(debug.WriteJSONArtifact(diagnostics.ArtifactLLMExecution, processreport.BuildLLMExecution(observations)))
warn(debug.WriteJSONArtifact(diagnostics.ArtifactCorrectionLedger, processreport.BuildCorrectionLedger(processreport.CorrectionLedgerInput{RunDirectoryPath: debug.Path(), RunOutput: &output})))
}
snapshot := processreport.Build(processreport.BuildInput{RunID: prepared.RunID, Status: reporting.StatusInProgress, StartedAt: prepared.Started,
ModuleSpecs: specs, RunOutput: &output, ProcessingError: runErr, SummaryOnly: !evidence.Reports})
return processResult{Transcript: output.FinalTranscript, Snapshot: snapshot}, runErr
}

View File

@@ -0,0 +1,72 @@
package cli
import (
"fmt"
"strings"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/reporting"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/outcomes"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/runner"
"gitea.maximumdirect.net/eric/audita/v4/internal/framework/structuredoutput"
)
func runnerProgress(progress func(string)) func(runner.Progress) {
if progress == nil {
return nil
}
return func(event runner.Progress) {
location := progressLocation(event.ModuleIndex, event.ModuleKey, event.ModuleID, event.SectionIndex)
message := location + " " + event.State
if event.Count != nil {
unit := "proposals"
if event.SectionIndex == nil {
unit = "corrections"
if event.State == "started" {
unit = "chunks"
}
}
message += fmt.Sprintf(" (%d %s)", *event.Count, unit)
}
progress(message)
}
}
func reportModelProgress(progress func(string), coordinates structuredoutput.DiagnosticContext, counts *outcomes.ExecutionCounts, err error) {
if coordinates.StageIndex == nil {
return
}
location := progressLocation(*coordinates.StageIndex, coordinates.ModuleKey, coordinates.StageID, coordinates.SectionIndex)
operation := strings.ReplaceAll(coordinates.Role, "_", " ")
if coordinates.ValidatorName != "" {
operation += " " + coordinates.ValidatorName
}
if coordinates.BatchIndex != nil {
operation += fmt.Sprintf(" batch %d", *coordinates.BatchIndex+1)
}
if coordinates.RepairAttempt != nil {
if coordinates.Role != "correction_repair" {
operation += " repair"
}
operation += fmt.Sprintf(" turn %d", *coordinates.RepairAttempt)
}
if counts == nil {
progress(fmt.Sprintf("%s %s started", location, operation))
return
}
outcome := "completed"
if err != nil {
outcome = "failed"
}
if counts.Available {
outcome += fmt.Sprintf(", %d provider attempts", counts.ProviderAttempts)
}
progress(fmt.Sprintf("%s %s finished (%s)", location, operation, outcome))
}
func progressLocation(index int, module string, id *string, section *int) string {
location := "Stage " + reporting.StageLabel(index, module, id)
if section != nil {
location += fmt.Sprintf(", chunk %d", *section+1)
}
return location
}

View File

@@ -2,269 +2,18 @@ package cli
import (
"context"
"flag"
"fmt"
"io"
"gitea.maximumdirect.net/eric/ReleaseKit/buildinfo"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/llm"
commandkit "go.maximumdirect.net/commandkit"
)
func sourceToCanonicalTranscript(source *schema.SourceTranscript) *schema.Transcript {
segments := make([]schema.Segment, len(source.Segments))
for i, s := range source.Segments {
id := i + 1
if s.ID != nil {
id = *s.ID
}
segments[i] = schema.Segment{
ID: id,
Speaker: s.Speaker,
Start: s.Start,
End: s.End,
Text: s.Text,
Categories: s.Categories,
}
}
return &schema.Transcript{Segments: segments}
}
// Run executes the Audita CLI with the provided arguments and streams.
// Run executes the application with the provided arguments and streams.
func Run(ctx context.Context, args []string, stdout, stderr io.Writer) int {
if len(args) == 0 {
writeRootUsage(stdout)
return 0
}
if len(args) == 2 && args[0] == "help" {
switch args[1] {
case "process":
writeProcessUsage(stdout)
return 0
case "config":
writeConfigUsage(stdout)
return 0
case "version":
writeVersionUsage(stdout)
return 0
}
}
if isHelpCommand(args) {
writeRootUsage(stdout)
return 0
}
if args[0] == "process" {
return runProcess(ctx, args[1:], stdout, stderr)
}
if args[0] == "config" {
return runConfig(ctx, args[1:], stdout, stderr)
}
if args[0] == "version" {
return runVersion(args[1:], stdout, stderr)
}
fmt.Fprintf(stderr, "audita: unknown command %q\n\n", args[0])
writeRootUsage(stderr)
return 2
}
func runVersion(args []string, stdout, stderr io.Writer) int {
flags := flag.NewFlagSet("version", flag.ContinueOnError)
flags.SetOutput(stderr)
flags.Usage = func() {} // Route usage after parsing so help stays on stdout.
if err := flags.Parse(args); err != nil {
if err == flag.ErrHelp {
writeVersionUsage(stdout)
return 0
}
writeVersionUsage(stderr)
return 2
}
if positional := flags.Args(); len(positional) > 0 {
fmt.Fprintf(stderr, "audita version: unexpected argument %q\n\n", positional[0])
writeVersionUsage(stderr)
return 2
}
fmt.Fprintf(stdout, "audita %s\n", buildinfo.Version())
return 0
}
func runConfig(ctx context.Context, args []string, stdout, stderr io.Writer) int {
if len(args) == 0 || isHelpCommand(args) || args[0] == "--help" || args[0] == "-h" {
writeConfigUsage(stdout)
return 0
}
switch args[0] {
case "validate":
return runConfigValidate(ctx, args[1:], stdout, stderr)
case "print-effective":
return runConfigPrintEffective(ctx, args[1:], stdout, stderr)
default:
fmt.Fprintf(stderr, "audita config: unknown command %q\n\n", args[0])
writeConfigUsage(stderr)
return 2
}
}
func runConfigValidate(ctx context.Context, args []string, stdout, stderr io.Writer) int {
input, help, err := parseConfigInput("validate", args, stderr)
app, err := buildApplication()
if err != nil {
fmt.Fprintf(stderr, "audita config validate: %s\n", configInputError(err))
return 2
}
if help {
writeConfigValidateUsage(stdout)
return 0
}
selected, err := loadConfigInput(input, "validate")
if err != nil {
fmt.Fprintf(stderr, "audita config validate: %s\n", configInputError(err))
return 2
}
if _, err := llm.NewRuntime(ctx, selected.Result.Config, selected.Path, nil); err != nil {
fmt.Fprintf(stderr, "audita config validate: %s\n", llm.RedactError(err, selected.Result.Config))
if ctx.Err() != nil || llm.IsAssetError(err) {
return 1
}
return 2
}
fmt.Fprintln(stdout, "config is valid")
return 0
}
func runConfigPrintEffective(ctx context.Context, args []string, stdout, stderr io.Writer) int {
input, help, err := parseConfigInput("print-effective", args, stderr)
if err != nil {
fmt.Fprintf(stderr, "audita config print-effective: %s\n", configInputError(err))
return 2
}
if help {
writeConfigPrintEffectiveUsage(stdout)
return 0
}
selected, err := loadConfigInput(input, "print-effective")
if err != nil {
fmt.Fprintf(stderr, "audita config print-effective: %s\n", configInputError(err))
return 2
}
llmRuntime, err := llm.NewRuntime(ctx, selected.Result.Config, selected.Path, nil)
if err != nil {
fmt.Fprintf(stderr, "audita config print-effective: %s\n", llm.RedactError(err, selected.Result.Config))
if ctx.Err() != nil || llm.IsAssetError(err) {
return 1
}
return 2
}
if input.View == "settings" {
err = selected.Result.WriteEffective(stdout)
} else {
var output []byte
if input.View == "profiles" {
output, err = llmRuntime.SelectedProfilesYAML()
} else {
output, err = llm.ExplanationYAML(selected.Result)
}
if err == nil {
_, err = stdout.Write(output)
}
}
if err != nil {
fmt.Fprintf(stderr, "audita config print-effective: %v\n", err)
fmt.Fprintln(stderr, err)
return 1
}
return 0
}
func isHelpCommand(args []string) bool {
if len(args) == 0 {
return false
}
if len(args) == 1 {
switch args[0] {
case "help", "-h", "--help":
return true
}
}
if len(args) == 2 && args[0] == "help" {
switch args[1] {
case "process":
return true
}
}
return false
}
func writeRootUsage(w io.Writer) {
fmt.Fprintln(w, "Audita is a transcript processing CLI.")
fmt.Fprintln(w)
fmt.Fprintln(w, "Usage:")
fmt.Fprintln(w, " audita <command> [options]")
fmt.Fprintln(w)
fmt.Fprintln(w, "Commands:")
fmt.Fprintln(w, " process Process a transcript JSON file")
fmt.Fprintln(w, " config Validate and inspect config")
fmt.Fprintln(w, " version Print the Audita version")
fmt.Fprintln(w)
fmt.Fprintln(w, "Example:")
fmt.Fprintln(w, " audita process transcript.json --glossary glossary.yaml --output corrected.json")
}
func writeVersionUsage(w io.Writer) {
fmt.Fprintln(w, "Print the Audita version.")
fmt.Fprintln(w)
fmt.Fprintln(w, "Usage:")
fmt.Fprintln(w, " audita version")
}
func writeConfigUsage(w io.Writer) {
fmt.Fprintln(w, "Validate and inspect Audita config.")
fmt.Fprintln(w)
fmt.Fprintln(w, "Usage:")
fmt.Fprintln(w, " audita config <command> [flags]")
fmt.Fprintln(w)
fmt.Fprintln(w, "Commands:")
fmt.Fprintln(w, " validate Validate a versioned YAML config file")
fmt.Fprintln(w, " print-effective Print redacted effective settings YAML")
}
func writeConfigValidateUsage(w io.Writer) {
fmt.Fprintln(w, "Validate a versioned YAML config file.")
fmt.Fprintln(w)
fmt.Fprintln(w, "Usage:")
fmt.Fprintln(w, " audita config validate --config <path> [--overlay <name>] [setting flags]")
}
func writeConfigPrintEffectiveUsage(w io.Writer) {
fmt.Fprintln(w, "Print redacted effective settings YAML.")
fmt.Fprintln(w)
fmt.Fprintln(w, "Usage:")
fmt.Fprintln(w, " audita config print-effective [--config <path>] [--overlay <name>] [setting flags]")
}
func writeProcessUsage(w io.Writer) {
fmt.Fprintln(w, "Process a transcript JSON file.")
fmt.Fprintln(w)
fmt.Fprintln(w, "Usage:")
fmt.Fprintln(w, " audita process <transcript.json> [flags]")
fmt.Fprintln(w)
fmt.Fprintln(w, "Flags:")
for _, name := range []string{
"config", "overlay", "glossary", "output",
"proposal-profile", "validation-profile", "modules", "output-schema",
"validation-max-prompt-tokens", "target-sections", "max-section-tokens", "min-section-tokens",
"normalize-max-segment-gap", "normalize-ellipsis-gap", "normalize-max-segment-duration", "normalize-max-segment-tokens",
"glossary-confidence-threshold", "homophones-confidence-threshold", "spoken-word-confidence-threshold", "grammar-confidence-threshold",
"transcript-description", "work-dir",
} {
fmt.Fprintf(w, " --%s\n", name)
}
fmt.Fprintln(w, " --reporting[=true|false] Write the three-file report bundle (default true)")
fmt.Fprintln(w, " --report-dir DIR Select the report directory (stdout setting for stdout; output parent by default for files)")
fmt.Fprintln(w, " --debug[=true|false] Persist detailed diagnostics (default false)")
fmt.Fprintln(w)
fmt.Fprintln(w, "Example:")
fmt.Fprintln(w, " audita process transcript.json --glossary glossary.yaml --output corrected.json")
return app.Execute(ctx, args, commandkit.Streams{Out: stdout, Err: stderr}).Status
}

View File

@@ -3,74 +3,113 @@ package cli
import (
"bytes"
"context"
"errors"
"os"
"path/filepath"
"strings"
"testing"
commandkit "go.maximumdirect.net/commandkit"
)
func writeRuntimeErrorConfig(t *testing.T, operatorDocument string) string {
t.Helper()
dir := t.TempDir()
profiles := filepath.Join(dir, "profiles")
if err := os.Mkdir(profiles, 0700); err != nil {
t.Fatal(err)
}
main := filepath.Join(dir, "config.yml")
configText := "version: 2\nprofiles_dir: profiles\nbackends:\n offline:\n endpoint: http://127.0.0.1:1/v1\n credential: AUDITA_TEST_PROVIDER_KEY\nllm:\n proposal_profile: proposal\n"
if err := os.WriteFile(main, []byte(configText), 0600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(profiles, "operator.yml"), []byte(operatorDocument), 0600); err != nil {
t.Fatal(err)
for name, body := range map[string]string{"config.yml": "version: 3\n", "prompts.yml": operatorDocument} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0600); err != nil {
t.Fatal(err)
}
}
return main
}
func TestConfigCommandsClassifyOperatorPromptErrorsAsInputErrors(t *testing.T) {
t.Setenv("AUDITA_TEST_PROVIDER_KEY", "synthetic-cli-redaction-secret")
func TestResourceCommandsRejectInvalidOperatorPrompts(t *testing.T) {
definitions := map[string]string{
"malformed operator YAML": "profiles:\n proposal: [\n",
"invalid operator template": "profiles:\n proposal:\n backend: offline\n model: local-model\nprompts:\n modules.grammar.proposal:\n v1:\n messages:\n - role: user\n content: '{{'\n",
"missing operator message resource": "profiles:\n proposal:\n backend: offline\n model: local-model\nprompts:\n modules.grammar.proposal:\n v1:\n messages:\n - role: user\n content_file: missing-instruction.md\n",
"malformed operator YAML": "profiles: [\n",
"invalid operator template": "collections:\n audita:\n prompts:\n - id: modules.grammar.proposal\n messages:\n - role: user\n content: '{{'\n output:\n format: text\n validation_mode: none\n",
"missing operator message resource": "collections:\n audita:\n prompts:\n - id: modules.grammar.proposal\n messages:\n - role: user\n content_file: missing-instruction.md\n output:\n format: text\n validation_mode: none\n",
}
commands := []struct {
name string
args []string
}{
{name: "validate", args: []string{"config", "validate"}},
{name: "print effective", args: []string{"config", "print-effective", "--view", "profiles"}},
for name, document := range definitions {
t.Run(name, func(t *testing.T) {
main := writeRuntimeErrorConfig(t, document)
var stdout, stderr bytes.Buffer
if code := Run(context.Background(), []string{"promptkit", "list", "prompts", "--config", main}, &stdout, &stderr); code == 0 {
t.Fatalf("invalid resource accepted: stdout=%q stderr=%q", stdout.String(), stderr.String())
}
})
}
for definition, document := range definitions {
for _, command := range commands {
t.Run(definition+"/"+command.name, func(t *testing.T) {
main := writeRuntimeErrorConfig(t, document)
args := append(append([]string(nil), command.args...), "--config", main)
var stdout, stderr bytes.Buffer
if code := Run(context.Background(), args, &stdout, &stderr); code != 2 {
t.Fatalf("exit=%d, stdout=%q, stderr=%q", code, stdout.String(), stderr.String())
}
if strings.Contains(stderr.String(), "synthetic-cli-redaction-secret") {
t.Fatalf("configured secret leaked: %q", stderr.String())
}
})
}
func TestMalformedCompanionReturnsInputFailure(t *testing.T) {
main := writeRuntimeErrorConfig(t, "profiles: [\n")
transcript := filepath.Join(filepath.Dir(main), "transcript.json")
if err := os.WriteFile(transcript, []byte("[]\n"), 0600); err != nil {
t.Fatal(err)
}
for _, args := range [][]string{
{"promptkit", "list", "prompts"},
{"config", "show", "--scope", "promptkit"},
{"process", transcript},
} {
var stdout, stderr bytes.Buffer
code := Run(context.Background(), append(args, "--config", main), &stdout, &stderr)
if code != 2 || !strings.Contains(stderr.String(), "yaml.invalid") || !strings.Contains(stderr.String(), "prompts.yml") || stdout.Len() != 0 {
t.Errorf("%v: status=%d want=2 stdout=%q stderr=%q", args, code, stdout.String(), stderr.String())
}
}
}
func TestConfigCommandsKeepCallerCancellationAsRuntimeExit(t *testing.T) {
t.Setenv("AUDITA_TEST_PROVIDER_KEY", "synthetic-cli-redaction-secret")
main := writeRuntimeErrorConfig(t, "profiles:\n proposal:\n backend: offline\n model: local-model\n")
commands := [][]string{
{"config", "validate", "--config", main},
{"config", "print-effective", "--config", main, "--view", "profiles"},
func TestUnreadableCompanionReturnsOperationalFailure(t *testing.T) {
main := writeRuntimeErrorConfig(t, "profiles: []\n")
companion := filepath.Join(filepath.Dir(main), "prompts.yml")
if err := os.Chmod(companion, 0); err != nil {
t.Fatal(err)
}
for _, args := range commands {
ctx, cancel := context.WithCancel(context.Background())
cancel()
if _, err := os.ReadFile(companion); !errors.Is(err, os.ErrPermission) {
t.Skipf("file permissions do not prevent reads: %v", err)
}
transcript := filepath.Join(filepath.Dir(main), "transcript.json")
if err := os.WriteFile(transcript, []byte("[]\n"), 0600); err != nil {
t.Fatal(err)
}
for _, args := range [][]string{
{"promptkit", "list", "prompts"},
{"config", "show", "--scope", "promptkit"},
{"process", transcript},
} {
var stdout, stderr bytes.Buffer
if code := Run(ctx, args, &stdout, &stderr); code != 1 {
t.Fatalf("args=%v exit=%d, stdout=%q, stderr=%q", args, code, stdout.String(), stderr.String())
code := Run(context.Background(), append(args, "--config", main), &stdout, &stderr)
if code != 1 || !strings.Contains(stderr.String(), "source.permission") || !strings.Contains(stderr.String(), "prompts.yml") || stdout.Len() != 0 {
t.Errorf("%v: status=%d want=1 stdout=%q stderr=%q", args, code, stdout.String(), stderr.String())
}
}
}
func TestResourceCommandKeepsCallerCancellationAsFailure(t *testing.T) {
main := writeRuntimeErrorConfig(t, "profiles:\n - id: proposal\n model: local-model\n")
transcript := filepath.Join(filepath.Dir(main), "transcript.json")
if err := os.WriteFile(transcript, []byte("[]\n"), 0600); err != nil {
t.Fatal(err)
}
app, err := buildApplication()
if err != nil {
t.Fatal(err)
}
ctx, cancel := context.WithCancel(context.Background())
cancel()
commands := map[string][]string{
"prompt catalog": {"promptkit", "list", "prompts", "--config", main},
"configuration": {"config", "show", "--scope", "promptkit", "--config", main},
"process": {"process", transcript, "--config", main},
}
for name, args := range commands {
t.Run(name, func(t *testing.T) {
var stdout, stderr bytes.Buffer
outcome := app.Execute(ctx, args, commandkit.Streams{Out: &stdout, Err: &stderr})
if outcome.Status != 1 || !errors.Is(outcome.Cause, context.Canceled) || stdout.Len() != 0 {
t.Fatalf("cancellation: status=%d cause=%v stdout=%q stderr=%q", outcome.Status, outcome.Cause, stdout.String(), stderr.String())
}
})
}
}

View File

@@ -7,7 +7,7 @@ import (
"strings"
"testing"
"gitea.maximumdirect.net/eric/ReleaseKit/buildinfo"
"go.maximumdirect.net/releasekit/buildinfo"
)
func TestVersionCommandRunsWithoutApplicationSetup(t *testing.T) {
@@ -30,12 +30,10 @@ func TestVersionCommandHelp(t *testing.T) {
args []string
want string
}{
{name: "root help", args: []string{"--help"}, want: "version Print the Audita version"},
{name: "root help", args: []string{"--help"}, want: "version Show application or CommandKit version."},
{name: "help version", args: []string{"help", "version"}, want: "audita version"},
{name: "short flag", args: []string{"version", "-h"}, want: "audita version"},
{name: "long flag", args: []string{"version", "--help"}, want: "audita version"},
{name: "parser help", args: []string{"version", "--h"}, want: "audita version"},
{name: "help short circuits", args: []string{"version", "-h", "--help", "extra"}, want: "audita version"},
} {
t.Run(test.name, func(t *testing.T) {
var stdout, stderr bytes.Buffer

View File

@@ -2,8 +2,9 @@ package chunking
import (
"fmt"
"slices"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
)
// Section represents a contiguous chunk of transcript segments with metadata.
@@ -100,66 +101,35 @@ func (c *Chunker) ChunkTranscript(transcript *schema.Transcript) ([]Section, err
totalTokens += segmentTokens[i]
}
minPossibleSections := c.calculateMinPossibleSections(segmentTokens)
var desiredSections int
useExplicitTarget := false
if c.config.TargetSections != nil {
desiredSections = *c.config.TargetSections
useExplicitTarget = true
if desiredSections <= 0 {
return nil, fmt.Errorf("target_sections must be positive, got %d", desiredSections)
}
if err := c.validateTargetSections(desiredSections, segmentTokens); err != nil {
return nil, err
}
} else {
desiredSections = ceilDiv(totalTokens, c.config.MaxSectionTokens)
if desiredSections < minPossibleSections {
desiredSections = minPossibleSections
}
if desiredSections < 1 {
desiredSections = 1
}
if desiredSections > len(transcript.Segments) {
desiredSections = len(transcript.Segments)
target := *c.config.TargetSections
if target <= 0 {
return nil, fmt.Errorf("target_sections must be positive, got %d", target)
}
return c.buildSectionsWithExplicitTarget(transcript.Segments, segmentTokens, target, ceilDiv(totalTokens, target))
}
targetTokensPerSection := ceilDiv(totalTokens, desiredSections)
if useExplicitTarget {
return c.buildSectionsWithExplicitTarget(
transcript.Segments,
segmentTokens,
desiredSections,
targetTokensPerSection,
)
}
return c.buildSectionsBalanced(transcript.Segments, segmentTokens, targetTokensPerSection), nil
desiredSections := ceilDiv(totalTokens, c.config.MaxSectionTokens)
desiredSections = max(desiredSections, c.calculateMinPossibleSections(segmentTokens), 1)
desiredSections = min(desiredSections, len(transcript.Segments))
return c.buildSectionsBalanced(transcript.Segments, segmentTokens, ceilDiv(totalTokens, desiredSections)), nil
}
// validateTargetSections checks if the target section count is achievable.
func (c *Chunker) validateTargetSections(target int, segmentTokens []int) error {
// Maximum possible sections: limited by segment count
maxPossibleSections := len(segmentTokens)
// InfeasibleTargetError indicates that a requested count cannot partition the
// normalized segments into nonempty, token-bounded sections.
type InfeasibleTargetError struct {
Target int
SegmentCount int
MinimumSections int
MaxSectionTokens int
}
if target > maxPossibleSections {
return fmt.Errorf(
"target_sections (%d) is impossible: cannot have more sections than segments (%d)",
target, maxPossibleSections)
func (e *InfeasibleTargetError) Error() string {
if e.Target > e.SegmentCount {
return fmt.Sprintf("target_sections (%d) is impossible: cannot have more sections than segments (%d)", e.Target, e.SegmentCount)
}
// Minimum possible sections: each segment must fit within max bounds
minPossibleSections := c.calculateMinPossibleSections(segmentTokens)
if target < minPossibleSections {
return fmt.Errorf(
"target_sections (%d) is impossible: need at least %d sections to respect max_section_tokens (%d)",
target, minPossibleSections, c.config.MaxSectionTokens)
}
return nil
return fmt.Sprintf("target_sections (%d) is impossible: need at least %d sections to respect max_section_tokens (%d)",
e.Target, e.MinimumSections, e.MaxSectionTokens)
}
// buildSectionsBalanced creates sections with a deterministic single-pass policy.
@@ -245,59 +215,63 @@ func (c *Chunker) calculateMinPossibleSections(segmentTokens []int) int {
return sections
}
// buildSectionsWithExplicitTarget builds exactly desiredSections when feasible.
// farthestLegalEnds records the exclusive end of the longest legal section
// starting at each segment, with oversized segments admitted only alone.
func farthestLegalEnds(segmentTokens []int, maximum int) []int {
ends := make([]int, len(segmentTokens))
end, windowTokens := 0, 0
for start, weight := range segmentTokens {
if weight > maximum {
end = start + 1
ends[start] = end
continue
}
for end < len(segmentTokens) && segmentTokens[end] <= maximum-windowTokens {
windowTokens += segmentTokens[end]
end++
}
ends[start] = end
windowTokens -= weight
}
return ends
}
// buildSectionsWithExplicitTarget builds exactly target nonempty sections when feasible.
func (c *Chunker) buildSectionsWithExplicitTarget(
segments []schema.Segment,
segmentTokens []int,
desiredSections int,
targetTokensPerSection int,
target, targetTokensPerSection int,
) ([]Section, error) {
n := len(segments)
cursor := 0
sections := make([]Section, 0, desiredSections)
for sectionIdx := 0; sectionIdx < desiredSections; sectionIdx++ {
if cursor >= n {
break
}
remainingSectionsAfter := desiredSections - sectionIdx - 1
currentSegments := []schema.Segment{segments[cursor]}
currentTokens := segmentTokens[cursor]
cursor++
for cursor < n {
remainingSegments := n - cursor
// Reserve one segment per future section to avoid empty sections.
if remainingSegments == remainingSectionsAfter {
break
}
nextTokens := segmentTokens[cursor]
if currentTokens+nextTokens > c.config.MaxSectionTokens {
break
}
if targetTokensPerSection == 0 || currentTokens < targetTokensPerSection {
currentSegments = append(currentSegments, segments[cursor])
currentTokens += nextTokens
cursor++
continue
}
break
}
sections = append(sections, c.buildSection(len(sections), currentSegments, currentTokens))
if target > n {
return nil, &InfeasibleTargetError{Target: target, SegmentCount: n}
}
farthest := farthestLegalEnds(segmentTokens, c.config.MaxSectionTokens)
minimum := make([]int, n+1)
for start := n - 1; start >= 0; start-- {
minimum[start] = 1 + minimum[farthest[start]]
}
if target < minimum[0] {
return nil, &InfeasibleTargetError{Target: target, SegmentCount: n, MinimumSections: minimum[0], MaxSectionTokens: c.config.MaxSectionTokens}
}
if cursor != n || len(sections) != desiredSections {
return nil, fmt.Errorf(
"target_sections (%d) is impossible under current constraints (got %d sections)",
desiredSections,
len(sections),
)
sections := make([]Section, 0, target)
start := 0
for i := range target {
remaining := target - i - 1
limit := min(farthest[start], n-remaining)
total := 0
for end := start + 1; end <= limit; end++ {
total += segmentTokens[end-1]
// Aim for the average where it leaves a feasible suffix. At
// the limit the suffix fits by construction.
if end == limit || (targetTokensPerSection > 0 && total >= targetTokensPerSection && minimum[end] <= remaining) {
sections = append(sections, c.buildSection(i, slices.Clone(segments[start:end]), total))
start = end
break
}
}
}
return sections, nil
}
@@ -308,5 +282,5 @@ func ceilDiv(numerator int, denominator int) int {
if numerator <= 0 {
return 0
}
return (numerator + denominator - 1) / denominator
return 1 + (numerator-1)/denominator
}

View File

@@ -1,10 +1,13 @@
package chunking
import (
"errors"
"math/bits"
"strconv"
"strings"
"testing"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
)
// mapTokenEstimator provides deterministic per-segment token counts for tests.
@@ -301,8 +304,9 @@ func TestChunkTargetSectionsImpossibleTooMany(t *testing.T) {
chunker := NewChunker(ChunkingConfig{MaxSectionTokens: 100, MinSectionTokens: 1, TargetSections: &target})
_, err := chunker.ChunkTranscript(makeTranscript(segments))
if err == nil {
t.Fatal("expected error for impossible target_sections")
var infeasible *InfeasibleTargetError
if !errors.As(err, &infeasible) || infeasible.SegmentCount != len(segments) {
t.Fatalf("expected typed segment-count error, got %v", err)
}
if !strings.Contains(err.Error(), "cannot have more sections than segments") {
t.Fatalf("unexpected error: %v", err)
@@ -318,14 +322,94 @@ func TestChunkTargetSectionsImpossibleTooFew(t *testing.T) {
)
_, err := chunker.ChunkTranscript(makeTranscript(segments))
if err == nil {
t.Fatal("expected error for impossible target_sections")
var infeasible *InfeasibleTargetError
if !errors.As(err, &infeasible) || infeasible.MinimumSections != 3 {
t.Fatalf("expected typed minimum-section error, got %v", err)
}
if !strings.Contains(err.Error(), "need at least 3 sections") {
t.Fatalf("unexpected error: %v", err)
}
}
func TestChunkExplicitTargetKeepsFeasibleSuffix(t *testing.T) {
segments := makeSegments([]string{"first", "second", "third"})
chunker := NewChunkerWithEstimator(
ChunkingConfig{MaxSectionTokens: 6, MinSectionTokens: 4, TargetSections: intPtr(2)},
&mapTokenEstimator{byText: map[string]int{"first": 2, "second": 5, "third": 1}},
)
sections, err := chunker.ChunkTranscript(makeTranscript(segments))
if err != nil || len(sections) != 2 || sections[0].EstimatedTokens != 2 || sections[1].EstimatedTokens != 6 {
t.Fatalf("wanted weights [2, 6], got %+v (%v)", sections, err)
}
assertSegmentCoverageAndOrder(t, segments, sections)
assertSectionMetadataConsistent(t, sections)
}
func TestChunkExplicitTargetsMatchEnumeratedPartitions(t *testing.T) {
// Enumerating cut masks gives an independent oracle for feasible counts,
// including zero-weight segments around oversized singletons.
const size, maximum = 5, 2
texts := make([]string, size)
for i := range texts {
texts[i] = strconv.Itoa(i)
}
segments := makeSegments(texts)
for sample := range 1 << (2 * size) {
var weights [size]int
byText := make(map[string]int, size)
for i, text := range texts {
weights[i] = (sample >> (2 * i)) & 3
byText[text] = weights[i]
}
var feasible [size + 1]bool
for cuts := range 1 << (size - 1) {
start, total := 0, 0
valid := true
for i, weight := range weights {
total += weight
if i == size-1 || cuts&(1<<i) != 0 {
if i > start && total > maximum {
valid = false
break
}
start, total = i+1, 0
}
}
if valid {
feasible[1+bits.OnesCount(uint(cuts))] = true
}
}
for target := 1; target <= size; target++ {
chunker := NewChunkerWithEstimator(
ChunkingConfig{MaxSectionTokens: maximum, TargetSections: &target},
&mapTokenEstimator{byText: byText},
)
sections, err := chunker.ChunkTranscript(makeTranscript(segments))
if !feasible[target] {
var infeasible *InfeasibleTargetError
if !errors.As(err, &infeasible) {
t.Fatalf("weights %v target %d should be infeasible, got %+v (%v)", weights, target, sections, err)
}
continue
}
if err != nil || len(sections) != target {
t.Fatalf("weights %v target %d should be feasible, got %+v (%v)", weights, target, sections, err)
}
assertSegmentCoverageAndOrder(t, segments, sections)
assertSectionMetadataConsistent(t, sections)
for _, section := range sections {
total := 0
for _, segment := range section.Segments {
total += weights[segment.ID-1]
}
if total != section.EstimatedTokens || (total > maximum && len(section.Segments) != 1) {
t.Fatalf("weights %v target %d yielded invalid section %+v", weights, target, section)
}
}
}
}
}
func TestChunkManySmallSegmentsBalanced(t *testing.T) {
texts := []string{"1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11"}
segments := makeSegments(texts)

View File

@@ -1,84 +0,0 @@
package chunking
// Summary provides a concise overview of chunking results for reports
type Summary struct {
ChunkCount int `json:"chunk_count"`
MinEstimatedTokens int `json:"min_estimated_chunk_tokens"`
MaxEstimatedTokens int `json:"max_estimated_chunk_tokens"`
TotalEstimatedTokens int `json:"total_estimated_transcript_tokens"`
TargetSections *int `json:"target_sections,omitempty"`
MaxSectionTokens int `json:"max_section_tokens"`
MinSectionTokens int `json:"min_section_tokens"`
}
// ChunkSummary represents a single chunk's metadata for diagnostics
type ChunkSummary struct {
Index int `json:"index"`
StartSegmentID int `json:"start_segment_id"`
EndSegmentID int `json:"end_segment_id"`
EstimatedTokens int `json:"estimated_tokens"`
SegmentCount int `json:"segment_count"`
}
// DetailedSummary provides per-chunk details for diagnostics
type DetailedSummary struct {
Summary `json:",inline"`
Chunks []ChunkSummary `json:"chunks"`
}
// ComputeSummary creates a Summary from sections and config
func ComputeSummary(sections []Section, config ChunkingConfig) Summary {
if len(sections) == 0 {
return Summary{
ChunkCount: 0,
MaxSectionTokens: config.MaxSectionTokens,
MinSectionTokens: config.MinSectionTokens,
TargetSections: config.TargetSections,
}
}
minTokens := sections[0].EstimatedTokens
maxTokens := sections[0].EstimatedTokens
totalTokens := 0
for _, sec := range sections {
if sec.EstimatedTokens < minTokens {
minTokens = sec.EstimatedTokens
}
if sec.EstimatedTokens > maxTokens {
maxTokens = sec.EstimatedTokens
}
totalTokens += sec.EstimatedTokens
}
return Summary{
ChunkCount: len(sections),
MinEstimatedTokens: minTokens,
MaxEstimatedTokens: maxTokens,
TotalEstimatedTokens: totalTokens,
TargetSections: config.TargetSections,
MaxSectionTokens: config.MaxSectionTokens,
MinSectionTokens: config.MinSectionTokens,
}
}
// ComputeDetailedSummary creates a DetailedSummary from sections and config
func ComputeDetailedSummary(sections []Section, config ChunkingConfig) DetailedSummary {
summary := ComputeSummary(sections, config)
chunks := make([]ChunkSummary, len(sections))
for i, sec := range sections {
chunks[i] = ChunkSummary{
Index: sec.Index,
StartSegmentID: sec.StartSegmentID,
EndSegmentID: sec.EndSegmentID,
EstimatedTokens: sec.EstimatedTokens,
SegmentCount: len(sec.Segments),
}
}
return DetailedSummary{
Summary: summary,
Chunks: chunks,
}
}

View File

@@ -1,148 +0,0 @@
package chunking
import (
"testing"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema"
)
func TestComputeSummary(t *testing.T) {
config := ChunkingConfig{
MaxSectionTokens: 100,
MinSectionTokens: 10,
}
sections := []Section{
{Index: 0, EstimatedTokens: 30, StartSegmentID: 1, EndSegmentID: 2},
{Index: 1, EstimatedTokens: 50, StartSegmentID: 3, EndSegmentID: 4},
{Index: 2, EstimatedTokens: 20, StartSegmentID: 5, EndSegmentID: 5},
}
summary := ComputeSummary(sections, config)
if summary.ChunkCount != 3 {
t.Errorf("expected chunk_count=3, got %d", summary.ChunkCount)
}
if summary.MinEstimatedTokens != 20 {
t.Errorf("expected min_estimated_tokens=20, got %d", summary.MinEstimatedTokens)
}
if summary.MaxEstimatedTokens != 50 {
t.Errorf("expected max_estimated_tokens=50, got %d", summary.MaxEstimatedTokens)
}
if summary.TotalEstimatedTokens != 100 {
t.Errorf("expected total_estimated_tokens=100, got %d", summary.TotalEstimatedTokens)
}
if summary.MaxSectionTokens != 100 {
t.Errorf("expected max_section_tokens=100, got %d", summary.MaxSectionTokens)
}
if summary.MinSectionTokens != 10 {
t.Errorf("expected min_section_tokens=10, got %d", summary.MinSectionTokens)
}
if summary.TargetSections != nil {
t.Errorf("expected target_sections=nil, got %v", summary.TargetSections)
}
}
func TestComputeSummaryWithTarget(t *testing.T) {
target := 5
config := ChunkingConfig{
MaxSectionTokens: 100,
MinSectionTokens: 10,
TargetSections: &target,
}
sections := []Section{
{Index: 0, EstimatedTokens: 30, StartSegmentID: 1, EndSegmentID: 2},
}
summary := ComputeSummary(sections, config)
if summary.TargetSections == nil || *summary.TargetSections != 5 {
t.Errorf("expected target_sections=5, got %v", summary.TargetSections)
}
}
func TestComputeSummaryEmptySections(t *testing.T) {
config := ChunkingConfig{
MaxSectionTokens: 100,
MinSectionTokens: 10,
}
sections := []Section{}
summary := ComputeSummary(sections, config)
if summary.ChunkCount != 0 {
t.Errorf("expected chunk_count=0, got %d", summary.ChunkCount)
}
if summary.MinEstimatedTokens != 0 {
t.Errorf("expected min_estimated_tokens=0 for empty, got %d", summary.MinEstimatedTokens)
}
if summary.MaxSectionTokens != 100 {
t.Errorf("expected max_section_tokens preserved, got %d", summary.MaxSectionTokens)
}
}
func TestComputeDetailedSummary(t *testing.T) {
config := ChunkingConfig{
MaxSectionTokens: 100,
MinSectionTokens: 10,
}
sections := []Section{
{
Index: 0,
EstimatedTokens: 30,
StartSegmentID: 1,
EndSegmentID: 2,
Segments: make([]schema.Segment, 2), // 2 segments
},
{
Index: 1,
EstimatedTokens: 50,
StartSegmentID: 3,
EndSegmentID: 5,
Segments: make([]schema.Segment, 3), // 3 segments
},
}
detailed := ComputeDetailedSummary(sections, config)
if detailed.ChunkCount != 2 {
t.Errorf("expected chunk_count=2, got %d", detailed.ChunkCount)
}
if len(detailed.Chunks) != 2 {
t.Fatalf("expected 2 chunk entries, got %d", len(detailed.Chunks))
}
// Check first chunk
if detailed.Chunks[0].Index != 0 {
t.Errorf("expected chunk[0].index=0, got %d", detailed.Chunks[0].Index)
}
if detailed.Chunks[0].StartSegmentID != 1 {
t.Errorf("expected chunk[0].start_segment_id=1, got %d", detailed.Chunks[0].StartSegmentID)
}
if detailed.Chunks[0].EndSegmentID != 2 {
t.Errorf("expected chunk[0].end_segment_id=2, got %d", detailed.Chunks[0].EndSegmentID)
}
if detailed.Chunks[0].EstimatedTokens != 30 {
t.Errorf("expected chunk[0].estimated_tokens=30, got %d", detailed.Chunks[0].EstimatedTokens)
}
if detailed.Chunks[0].SegmentCount != 2 {
t.Errorf("expected chunk[0].segment_count=2, got %d", detailed.Chunks[0].SegmentCount)
}
// Check second chunk
if detailed.Chunks[1].Index != 1 {
t.Errorf("expected chunk[1].index=1, got %d", detailed.Chunks[1].Index)
}
if detailed.Chunks[1].StartSegmentID != 3 {
t.Errorf("expected chunk[1].start_segment_id=3, got %d", detailed.Chunks[1].StartSegmentID)
}
if detailed.Chunks[1].EndSegmentID != 5 {
t.Errorf("expected chunk[1].end_segment_id=5, got %d", detailed.Chunks[1].EndSegmentID)
}
if detailed.Chunks[1].SegmentCount != 3 {
t.Errorf("expected chunk[1].segment_count=3, got %d", detailed.Chunks[1].SegmentCount)
}
}

View File

@@ -1,7 +1,6 @@
package chunking
import (
"strings"
"unicode"
)
@@ -24,24 +23,39 @@ func NewSimpleTokenEstimator() *SimpleTokenEstimator {
// This implementation uses a simple heuristic: count words and punctuation as tokens.
// The estimate is deterministic and stable for the same input text.
func (e *SimpleTokenEstimator) EstimateTokens(text string) int {
if text == "" {
return 0
}
var count TokenCount
count.Add(text)
return count.Estimate()
}
// Simple heuristic: split on whitespace and count non-empty segments
words := strings.Fields(text)
tokenCount := len(words)
// CountComponents returns unrounded counts for budgets composed from fragments.
func (e *SimpleTokenEstimator) CountComponents(text string) (words, punctuation int) {
var count TokenCount
count.Add(text)
return count.words, count.punctuation
}
// Add some estimate for punctuation that might be separate tokens
punctuationCount := 0
// TokenCount can be copied and extended with adjacent text fragments.
type TokenCount struct {
words, punctuation int
inWord bool
}
func (c *TokenCount) Add(text string) {
for _, r := range text {
nonspace := !unicode.IsSpace(r)
if nonspace && !c.inWord {
c.words++
}
c.inWord = nonspace
if unicode.IsPunct(r) && r != '\'' && r != '-' && r != '_' {
punctuationCount++
c.punctuation++
}
}
}
// Rough estimate: each word is a token, plus half the punctuation as separate tokens
return tokenCount + (punctuationCount / 2)
func (c TokenCount) Estimate() int {
return c.words + c.punctuation/2
}
// ConstTokenEstimator returns a constant token count for testing purposes.

View File

@@ -5,49 +5,65 @@ import (
"strings"
"time"
ck "gitea.maximumdirect.net/eric/ConfigKit"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/modulecatalog"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/outputschema"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/modulecatalog"
"gitea.maximumdirect.net/eric/audita/v4/internal/core/outputschema"
ck "go.maximumdirect.net/configkit"
)
const (
DefaultModulesCSV = "glossary,homophones,glossary,spoken_word,grammar"
DefaultTranscriptDescriptionMaxChars = 500
DefaultValidationMaxPromptTokens = 2048
)
// Config is the version-2 application configuration. Invocation paths are not settings.
// Config contains application settings. Invocation paths are not settings.
type Config struct {
Version int `yaml:"version"`
ProfilesDir string `yaml:"profiles_dir"`
Backends map[string]Backend `yaml:"backends"`
LLM LLM `yaml:"llm"`
Pipeline Pipeline `yaml:"pipeline"`
Output Output `yaml:"output"`
Validation Validation `yaml:"validation"`
Chunking Chunking `yaml:"chunking"`
Normalization Normalization `yaml:"normalization"`
Thresholds Thresholds `yaml:"thresholds"`
Context Context `yaml:"context"`
Reporting Reporting `yaml:"reporting"`
Diagnostics Diagnostics `yaml:"diagnostics"`
Version int `yaml:"version"`
Glossaries []string `yaml:"glossaries"`
ProtectedTerms []string `yaml:"protected_terms"`
GlossaryCollections map[string]GlossaryCollection `yaml:"glossary_collections"`
LLM LLM `yaml:"llm"`
Pipeline Pipeline `yaml:"pipeline"`
Output Output `yaml:"output"`
Validation Validation `yaml:"validation"`
Chunking Chunking `yaml:"chunking"`
Normalization Normalization `yaml:"normalization"`
Context Context `yaml:"context"`
Reporting Reporting `yaml:"reporting"`
Diagnostics Diagnostics `yaml:"diagnostics"`
}
type Backend struct {
Endpoint string `yaml:"endpoint"`
Concurrency int `yaml:"concurrency"`
QueueCapacity int `yaml:"queue_capacity"`
Credential *ck.Secret `yaml:"credential"`
type GlossaryCollection struct {
Entries []GlossaryEntry `yaml:"entries"`
}
type GlossaryEntry struct {
ID string `yaml:"id"`
Name string `yaml:"name"`
Category string `yaml:"category"`
Description string `yaml:"description"`
Aliases []string `yaml:"aliases"`
Plural *string `yaml:"plural"`
Extra map[string]any `yaml:",inline"`
}
type LLM struct {
ProposalProfile string `yaml:"proposal_profile"`
ValidationProfile string `yaml:"validation_profile"`
TransientRetries int `yaml:"transient_retries"`
RepairAttempts int `yaml:"repair_attempts"`
OperationTimeout time.Duration `yaml:"operation_timeout"`
ProposalProfile *string `yaml:"proposal_profile"`
ValidationProfile *string `yaml:"validation_profile"`
CorrectionRepairProfile *string `yaml:"correction_repair_profile"`
CorrectionRepairAttempts int `yaml:"correction_repair_attempts"`
TransientRetries int `yaml:"transient_retries"`
RepairAttempts int `yaml:"repair_attempts"`
OperationTimeout time.Duration `yaml:"operation_timeout"`
}
type Pipeline struct {
Modules []string `yaml:"modules"`
Stages []Stage `yaml:"stages"`
}
type Stage struct {
Module string `yaml:"module"`
ID *string `yaml:"id"`
Glossaries []string `yaml:"glossaries"`
ProtectedTerms []string `yaml:"protected_terms"`
LLM LLM `yaml:"llm"`
Validation Validation `yaml:"validation"`
Context Context `yaml:"context"`
}
type Output struct {
Schema string `yaml:"schema"`
@@ -66,17 +82,10 @@ type Normalization struct {
MaxSegmentDuration float64 `yaml:"max_segment_duration"`
MaxSegmentTokens int `yaml:"max_segment_tokens"`
}
type Thresholds struct {
Glossary float64 `yaml:"glossary"`
Homophones float64 `yaml:"homophones"`
SpokenWord float64 `yaml:"spoken_word"`
Grammar float64 `yaml:"grammar"`
}
type Context struct {
Description string `yaml:"description"`
}
type Diagnostics struct {
Debug bool `yaml:"debug"`
WorkDir string `yaml:"work_dir"`
}
type Reporting struct {
@@ -86,51 +95,46 @@ type Reporting struct {
func defaults() Config {
return Config{
ProfilesDir: "profiles",
LLM: LLM{TransientRetries: 2, RepairAttempts: 2, OperationTimeout: 15 * time.Minute},
Pipeline: Pipeline{Modules: []string{"glossary", "homophones", "glossary", "spoken_word", "grammar"}},
Version: 3,
LLM: LLM{TransientRetries: 2, RepairAttempts: 2, CorrectionRepairAttempts: 1, OperationTimeout: 15 * time.Minute},
Pipeline: Pipeline{Stages: []Stage{{Module: "glossary"}, {Module: "homophones"}, {Module: "glossary"}, {Module: "spoken_word"}, {Module: "grammar"}}},
Output: Output{Schema: "bare-segments"},
Validation: Validation{MaxPromptTokens: DefaultValidationMaxPromptTokens},
Chunking: Chunking{MaxSectionTokens: 8192, MinSectionTokens: 2048},
Normalization: Normalization{MaxSegmentGap: 4, EllipsisGap: 3.5, MaxSegmentDuration: 60, MaxSegmentTokens: 2048},
Thresholds: Thresholds{Glossary: .8, Homophones: .8, SpokenWord: .8, Grammar: .8},
Reporting: Reporting{Enabled: true, StdoutDir: "."},
Diagnostics: Diagnostics{WorkDir: "/tmp/audita"},
}
}
// Load resolves the selected main file, optional overlay, and explicit setting overrides.
// Its result retains safe effective output and provenance for CLI composition.
func Load(source ck.Source, overlay string, overrides ...ck.Override) (*ck.Result[Config], error) {
return ck.Load(source, ck.Options[Config]{
const glossaryImports = `config:
imports:
- path: glossary.yml
required: false
destination: [glossary_collections]
- dir: glossary
required: false
recursive: true
pattern: ["*.yml", "*.yaml"]
destination: [glossary_collections]
`
// Load resolves the selected main source and preserves native source evidence.
func Load(input ck.Input, overlay string, overrides ...ck.Override) (*ck.Result[Config], error) {
input.Imports = true
return ck.LoadLayered(input, ck.LayeredOptions[Config]{
Overlay: overlay, Overrides: overrides,
Underlays: []ck.Underlay{{Inputs: []ck.Input{{Source: ck.Bytes("Audita glossary imports", []byte(glossaryImports)), Imports: true, MainRelative: ck.MainRelative()}}}},
Definition: ck.Definition[Config]{
Defaults: defaults,
Defaults: defaults,
SequenceIdentities: []ck.SequenceIdentity{ck.SequenceIdentityMatching(ck.SequenceSelector{ck.SequenceLiteralKey("glossary_collections"), ck.SequenceAnyMappingKey(), ck.SequenceLiteralKey("entries")}, "id")},
Version: &ck.VersionRule{Path: ck.Keys("version"), Check: func(version ck.Version, v *ck.Validation) error {
if !version.Present || version.Null || version.Text != "2" {
v.Error(ck.Keys("version"), "version 2 is required; see docs/migrations/v2.md")
if version.Present && (version.Null || version.Text != "3") {
v.Error(ck.Keys("version"), "use application configuration version 3; see docs/migrations/v3.md")
}
return nil
}},
Resolve: func(c *Config, r *ck.Resolution) error {
ck.Default(r, ck.Keys("llm", "validation_profile"), &c.LLM.ValidationProfile, c.LLM.ProposalProfile, "validation uses the final proposal profile when omitted", ck.Keys("llm", "proposal_profile"))
for id, backend := range c.Backends {
changed := false
if !r.IsExplicit(ck.Keys("backends", id, "concurrency")) {
backend.Concurrency = 1
changed = true
}
if !r.IsExplicit(ck.Keys("backends", id, "queue_capacity")) {
backend.QueueCapacity = 1024
changed = true
}
if changed {
c.Backends[id] = backend
r.Record(ck.Keys("backends", id), ck.ChangeDerivedDefault, "finite backend defaults")
}
}
return nil
},
Resolve: resolveSettings,
Validate: validate,
},
})
@@ -142,24 +146,41 @@ func validate(c *Config, v *ck.Validation) {
v.Error(path, message)
}
}
check(strings.TrimSpace(c.ProfilesDir) != "", ck.Keys("profiles_dir"), "profile directory is required")
check(strings.TrimSpace(c.LLM.ProposalProfile) != "", ck.Keys("llm", "proposal_profile"), "proposal profile is required")
check(strings.TrimSpace(c.LLM.ValidationProfile) != "", ck.Keys("llm", "validation_profile"), "validation profile is required")
check(c.LLM.TransientRetries >= 0, ck.Keys("llm", "transient_retries"), "retry budget must be non-negative")
check(c.LLM.RepairAttempts >= 0 && c.LLM.RepairAttempts <= 3, ck.Keys("llm", "repair_attempts"), "repair attempts must be between zero and three")
check(c.LLM.OperationTimeout > 0, ck.Keys("llm", "operation_timeout"), "operation timeout must be positive")
check(len(c.Backends) > 0, ck.Keys("backends"), "at least one backend is required")
for id, b := range c.Backends {
p := ck.Keys("backends", id)
check(strings.TrimSpace(b.Endpoint) != "", p.Key("endpoint"), "backend endpoint is required")
check(b.Concurrency > 0, p.Key("concurrency"), "backend concurrency must be positive")
check(b.QueueCapacity >= 0, p.Key("queue_capacity"), "queue capacity must be non-negative")
for name, collection := range c.GlossaryCollections {
for i, entry := range collection.Entries {
path := ck.Keys("glossary_collections", name, "entries").Index(i)
check(entry.ID != "", path.Key("id"), "entry id must not be empty")
check(entry.Name != "", path.Key("name"), "entry name must not be empty")
check(entry.Category != "", path.Key("category"), "entry category must not be empty")
for index, alias := range entry.Aliases {
check(alias != "", path.Key("aliases").Index(index), "alias must not be empty")
}
check(entry.Plural == nil || *entry.Plural != "", path.Key("plural"), "plural must not be empty")
}
}
for i, module := range c.Pipeline.Modules {
check(modulecatalog.IsSupported(module), ck.Keys("pipeline", "modules").Index(i), "unsupported module key")
validateRuntimeSettings(check, ck.Keys(), c.LLM, c.Validation, c.Context)
validateSelections := func(values []string, path ck.Path) {
for i, name := range values {
_, exists := c.GlossaryCollections[name]
check(exists, path.Index(i), "unknown glossary collection")
}
}
validateSelections(c.Glossaries, ck.Keys("glossaries"))
validateSelections(c.ProtectedTerms, ck.Keys("protected_terms"))
ids := make(map[string]bool)
for i, item := range c.Pipeline.Stages {
path := ck.Keys("pipeline", "stages").Index(i)
check(modulecatalog.IsSupported(item.Module), path.Key("module"), "unsupported module key")
if item.ID != nil {
check(*item.ID != "", path.Key("id"), "id must not be empty")
check(!ids[*item.ID], path.Key("id"), "id must be unique")
ids[*item.ID] = true
}
validateSelections(item.Glossaries, path.Key("glossaries"))
validateSelections(item.ProtectedTerms, path.Key("protected_terms"))
validateRuntimeSettings(check, path, item.LLM, item.Validation, item.Context)
}
check(outputschema.IsSupported(c.Output.Schema), ck.Keys("output", "schema"), "unsupported output schema")
check(c.Validation.MaxPromptTokens > 0, ck.Keys("validation", "max_prompt_tokens"), "validation prompt budget must be positive")
check(c.Chunking.MaxSectionTokens > 0, ck.Keys("chunking", "max_section_tokens"), "maximum section tokens must be positive")
check(c.Chunking.MinSectionTokens > 0 && c.Chunking.MinSectionTokens <= c.Chunking.MaxSectionTokens, ck.Keys("chunking", "min_section_tokens"), "minimum section tokens must be positive and no greater than maximum")
check(c.Chunking.TargetSections == nil || *c.Chunking.TargetSections > 0, ck.Keys("chunking", "target_sections"), "target sections must be positive when set")
@@ -167,23 +188,16 @@ func validate(c *Config, v *ck.Validation) {
check(c.Normalization.EllipsisGap >= 0, ck.Keys("normalization", "ellipsis_gap"), "ellipsis gap must be non-negative")
check(c.Normalization.MaxSegmentDuration > 0, ck.Keys("normalization", "max_segment_duration"), "maximum segment duration must be positive")
check(c.Normalization.MaxSegmentTokens > 0, ck.Keys("normalization", "max_segment_tokens"), "maximum segment tokens must be positive")
for name, threshold := range map[string]float64{"glossary": c.Thresholds.Glossary, "homophones": c.Thresholds.Homophones, "spoken_word": c.Thresholds.SpokenWord, "grammar": c.Thresholds.Grammar} {
check(threshold >= 0 && threshold <= 1, ck.Keys("thresholds", name), "confidence threshold must be between zero and one")
}
check(len(strings.TrimSpace(c.Context.Description)) <= DefaultTranscriptDescriptionMaxChars, ck.Keys("context", "description"), fmt.Sprintf("description must be at most %d bytes after trimming", DefaultTranscriptDescriptionMaxChars))
}
// ParseModulesCSV is used only for an explicitly supplied --modules override.
func ParseModulesCSV(raw string) ([]string, error) {
if raw == "" {
return []string{}, nil
}
parts := strings.Split(raw, ",")
for i := range parts {
parts[i] = strings.TrimSpace(parts[i])
if parts[i] == "" {
return nil, fmt.Errorf("modules list contains an empty value")
}
}
return parts, nil
func validateRuntimeSettings(check func(bool, ck.Path, string), base ck.Path, settings LLM, validation Validation, context Context) {
llm := base.Key("llm")
check(settings.TransientRetries >= 0, llm.Key("transient_retries"), "retry budget must be non-negative")
check(settings.RepairAttempts >= 0 && settings.RepairAttempts <= 3, llm.Key("repair_attempts"), "repair attempts must be between zero and three")
check(settings.CorrectionRepairAttempts >= 0, llm.Key("correction_repair_attempts"), "correction repair attempts must be non-negative")
check(settings.CorrectionRepairProfile == nil || *settings.CorrectionRepairProfile != "", llm.Key("correction_repair_profile"), "correction repair profile must not be empty; use null to clear it")
check(settings.OperationTimeout > 0, llm.Key("operation_timeout"), "operation timeout must be positive")
check(settings.ValidationProfile == nil || *settings.ValidationProfile != "", llm.Key("validation_profile"), "validation profile must not be empty; use null to clear it")
check(validation.MaxPromptTokens > 0, base.Key("validation").Key("max_prompt_tokens"), "validation prompt budget must be positive")
check(len(strings.TrimSpace(context.Description)) <= DefaultTranscriptDescriptionMaxChars, base.Key("context").Key("description"), fmt.Sprintf("description must be at most %d bytes after trimming", DefaultTranscriptDescriptionMaxChars))
}

View File

@@ -1,303 +1,198 @@
package config
import (
"bytes"
"errors"
"io/fs"
"os"
"path"
"path/filepath"
"reflect"
"strings"
"testing"
ck "gitea.maximumdirect.net/eric/ConfigKit"
ck "go.maximumdirect.net/configkit"
)
const base = "version: 2\nbackends:\n local:\n endpoint: https://local.invalid/v1\nllm:\n proposal_profile: proposal\n"
func loadText(text, overlay string, overrides ...ck.Override) (*ck.Result[Config], error) {
return Load(ck.Bytes("config.yml", []byte(text)), overlay, overrides...)
}
func TestDefaultsAndDomainSettings(t *testing.T) {
loaded, err := loadText(base, "")
func TestDefaultsAndVersion(t *testing.T) {
result, err := Load(ck.Input{Source: ck.NoSource()}, "")
if err != nil {
t.Fatal(err)
}
c := loaded.Config
if c.LLM.ValidationProfile != "proposal" || c.Backends["local"].Concurrency != 1 || c.Backends["local"].QueueCapacity != 1024 {
t.Fatalf("derived settings: %+v %+v", c.LLM, c.Backends)
if result.Config.Version != 3 || len(result.Config.Pipeline.Stages) != 5 {
t.Fatalf("defaults: %+v", result.Config)
}
if !reflect.DeepEqual(c.Pipeline.Modules, []string{"glossary", "homophones", "glossary", "spoken_word", "grammar"}) {
t.Fatalf("module order: %v", c.Pipeline.Modules)
}
if explanation, ok := loaded.Explain(ck.Keys("llm", "validation_profile")); !ok || len(explanation.History) == 0 {
t.Fatal("validation inheritance has no recorded derivation")
}
if _, err := loadText(base+"pipeline:\n modules: []\n", ""); err != nil {
t.Fatalf("empty pipeline: %v", err)
}
if _, err := loadText(base+"pipeline:\n modules: [grammar, glossary, grammar]\n", ""); err != nil {
t.Fatalf("repeated modules: %v", err)
}
}
func TestStrictInputAndConstraints(t *testing.T) {
for _, tc := range []struct{ name, text string }{
{"old version", strings.Replace(base, "version: 2", "version: 1", 1)},
{"missing version", strings.Replace(base, "version: 2\n", "", 1)},
{"null version", strings.Replace(base, "version: 2", "version: null", 1)},
{"quoted version", strings.Replace(base, "version: 2", "version: '2'", 1)},
{"unknown field", base + "mystery: true\n"},
{"empty validation profile", base + " validation_profile: ''\n"},
{"null validation profile", base + " validation_profile: null\n"},
{"null proposal profile", strings.Replace(base, "proposal_profile: proposal", "proposal_profile: null", 1)},
{"zero backend concurrency", base + " concurrency: 0\n"},
{"invalid target", base + "chunking:\n target_sections: 0\n"},
{"invalid section relation", base + "chunking:\n min_section_tokens: 10000\n"},
{"string normalization", base + "normalization:\n max_segment_gap: 4s\n"},
{"invalid threshold", base + "thresholds:\n glossary: 1.1\n"},
{"removed retention", base + "diagnostics:\n retention: always\n"},
} {
t.Run(tc.name, func(t *testing.T) {
if _, err := loadText(tc.text, ""); err == nil {
t.Fatal("invalid config accepted")
}
})
}
_, err := loadText(strings.Replace(base, "version: 2", "version: 1", 1), "")
var loadErr *ck.LoadError
if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) == 0 || !strings.Contains(loadErr.Diagnostics()[0].Message, "docs/migrations/v2.md") {
t.Fatalf("migration guidance: %v", err)
}
for _, tc := range []struct{ name, text string }{
{"optional target null", base + "chunking:\n target_sections: null\n"},
{"zero queue", strings.Replace(base, "llm:\n", " queue_capacity: 0\nllm:\n", 1)},
{"zero retries", base + " transient_retries: 0\n repair_attempts: 0\n"},
{"zero threshold", base + "thresholds:\n grammar: 0\n"},
} {
t.Run(tc.name, func(t *testing.T) {
if _, err := loadText(tc.text, ""); err != nil {
t.Fatal(err)
}
})
}
}
func TestOverlayOverrideAndInheritance(t *testing.T) {
dir := t.TempDir()
if err := os.Mkdir(filepath.Join(dir, "overlays"), 0700); err != nil {
t.Fatal(err)
}
main := filepath.Join(dir, "config.yml")
if err := os.WriteFile(main, []byte(base), 0600); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(dir, "overlays", "testing.yml"), []byte("llm:\n proposal_profile: testing\nchunking:\n max_section_tokens: 1000\n"), 0600); err != nil {
t.Fatal(err)
}
loaded, err := Load(ck.File(main), "testing", ck.Override{Path: ck.Keys("llm", "proposal_profile"), Value: "explicit", Flag: "--proposal-profile"}, ck.Override{Path: ck.Keys("chunking", "min_section_tokens"), Value: 500, Flag: "--min-section-tokens"})
if err != nil {
t.Fatal(err)
}
if loaded.Config.LLM.ProposalProfile != "explicit" || loaded.Config.LLM.ValidationProfile != "explicit" || loaded.Config.Chunking.MaxSectionTokens != 1000 || loaded.Config.Chunking.MinSectionTokens != 500 {
t.Fatalf("resolved: %+v", loaded.Config)
}
if got, _ := loaded.Metadata().Lookup(ck.Keys("llm", "proposal_profile")); got.Origin.Layer != ck.LayerCLI {
t.Fatalf("override origin: %+v", got)
}
if got, _ := loaded.Metadata().Lookup(ck.Keys("chunking", "max_section_tokens")); got.Origin.Layer != ck.LayerOverlay {
t.Fatalf("overlay origin: %+v", got)
}
}
func TestSurvivingCredentials(t *testing.T) {
t.Setenv("BASE_SECRET", "")
t.Setenv("NEW_SECRET", "synthetic-secret")
withSecret := strings.Replace(base, "llm:\n", " other:\n endpoint: https://other.invalid/v1\n credential: BASE_SECRET\nllm:\n", 1)
if _, err := loadText(withSecret, ""); err == nil {
t.Fatal("missing unselected backend secret accepted")
}
replacement := ck.Override{Path: ck.Keys("backends", "other", "credential"), Value: "NEW_SECRET", Flag: "--credential"}
loaded, err := loadText(withSecret, "", replacement)
if err != nil {
t.Fatal(err)
}
if got := loaded.Config.Backends["other"].Credential.Value(); got != "synthetic-secret" {
t.Fatalf("resolved secret: %q", got)
}
var effective bytes.Buffer
if err := loaded.WriteEffective(&effective); err != nil {
t.Fatal(err)
}
if strings.Contains(effective.String(), "synthetic-secret") {
t.Fatal("effective output leaked a secret")
}
null := ck.Override{Path: ck.Keys("backends", "other", "credential"), Value: nil, Flag: "--credential"}
loaded, err = loadText(withSecret, "", null)
if err != nil || loaded.Config.Backends["other"].Credential != nil {
t.Fatalf("null credential: %+v %v", loaded, err)
}
inherited := `version: 2
backends:
parent:
endpoint: https://parent.invalid/v1
credential: BASE_SECRET
local:
extends: parent
credential: null
llm:
proposal_profile: proposal
`
if _, err := loadText(inherited, ""); err == nil {
t.Fatal("null child credential removed the unselected parent's surviving reference")
}
t.Setenv("BASE_SECRET", "synthetic-parent-secret")
loaded, err = loadText(strings.Replace(inherited, " credential: null\n", "", 1), "")
if err != nil {
t.Fatal(err)
}
if got := loaded.Config.Backends["local"].Credential.Value(); got != "synthetic-parent-secret" {
t.Fatalf("inherited secret: %q", got)
}
if got := loaded.Metadata().IsExplicit(ck.Keys("backends", "local", "credential")); !got {
t.Fatal("inherited credential is not explicit")
}
var inheritedEffective bytes.Buffer
if err := loaded.WriteEffective(&inheritedEffective); err != nil {
t.Fatal(err)
}
if strings.Contains(inheritedEffective.String(), "synthetic-parent-secret") {
t.Fatal("effective output leaked an inherited secret")
}
loaded, err = loadText(inherited, "")
if err != nil || loaded.Config.Backends["local"].Credential != nil {
t.Fatalf("child null credential: %+v %v", loaded, err)
}
if got := loaded.Config.Backends["parent"].Credential.Value(); got != "synthetic-parent-secret" {
t.Fatalf("parent credential after child null: %q", got)
}
t.Setenv("AUDITA_MODEL", "legacy-model")
loaded, err = loadText(base, "")
if err != nil || loaded.Config.LLM.ProposalProfile != "proposal" {
t.Fatalf("legacy environment affected loading: %+v %v", loaded, err)
}
}
func TestSiblingInheritancePreservesBackendSettings(t *testing.T) {
text := `version: 2
backends:
base:
endpoint: https://base.invalid/v1
concurrency: 3
queue_capacity: 0
local:
extends: base
llm:
proposal_profile: proposal
`
loaded, err := loadText(text, "")
if err != nil {
t.Fatal(err)
}
backend := loaded.Config.Backends["local"]
if backend.Endpoint != "https://base.invalid/v1" || backend.Concurrency != 3 || backend.QueueCapacity != 0 {
t.Fatalf("inherited backend settings: %+v", backend)
}
for _, path := range []ck.Path{
ck.Keys("backends", "local", "endpoint"),
ck.Keys("backends", "local", "concurrency"),
ck.Keys("backends", "local", "queue_capacity"),
} {
if !loaded.Metadata().IsExplicit(path) {
t.Errorf("inherited field %s is not explicit", path.String())
path := filepath.Join(t.TempDir(), "config.yml")
for _, text := range []string{"version: 2\n", "version: null\n", "version: invalid\n"} {
if err := os.WriteFile(path, []byte(text), 0644); err != nil {
t.Fatal(err)
}
if _, err := Load(ck.Input{Source: ck.File(path)}, ""); err == nil {
t.Fatalf("accepted %q", text)
}
}
overridden, err := loadText(strings.Replace(text, " extends: base\n", " extends: base\n concurrency: 2\n", 1), "")
if err := os.WriteFile(path, []byte("pipeline:\n stages: []\n"), 0644); err != nil {
t.Fatal(err)
}
empty, err := Load(ck.Input{Source: ck.File(path)}, "")
if err != nil {
t.Fatal(err)
}
if got := overridden.Config.Backends["local"].Concurrency; got != 2 {
t.Fatalf("child concurrency override: %d", got)
}
if got := overridden.Config.Backends["local"].QueueCapacity; got != 0 {
t.Fatalf("inherited zero queue capacity: %d", got)
if len(empty.Config.Pipeline.Stages) != 0 {
t.Fatal("empty pipeline was not preserved")
}
}
func TestSiblingInheritanceUsesSelectedOverlay(t *testing.T) {
func TestMainContextImportsAndOverlay(t *testing.T) {
dir := t.TempDir()
if err := os.Mkdir(filepath.Join(dir, "overlays"), 0700); err != nil {
if err := os.Mkdir(filepath.Join(dir, "overlays"), 0755); err != nil {
t.Fatal(err)
}
main := filepath.Join(dir, "config.yml")
text := `version: 2
backends:
base:
endpoint: https://base.invalid/v1
concurrency: 3
queue_capacity: 0
local:
extends: base
concurrency: 2
llm:
proposal_profile: proposal
`
if err := os.WriteFile(main, []byte(text), 0600); err != nil {
t.Fatal(err)
for name, contents := range map[string]string{
"main.yml": "version: 3\nconfig:\n imports:\n - path: fragment.yml\noutput:\n schema: bare-segments\n",
"fragment.yml": "context:\n description: imported\n",
"overlays/selected.yml": "context:\n description: overlay\n",
} {
if err := os.WriteFile(filepath.Join(dir, name), []byte(contents), 0644); err != nil {
t.Fatal(err)
}
}
if err := os.WriteFile(filepath.Join(dir, "overlays", "testing.yml"), []byte("backends:\n base:\n endpoint: https://overlay.invalid/v1\n concurrency: 4\n"), 0600); err != nil {
t.Fatal(err)
}
loaded, err := Load(ck.File(main), "testing")
result, err := Load(ck.Input{Source: ck.File(filepath.Join(dir, "main.yml"))}, "selected", ck.Override{Path: ck.Keys("context", "description"), Value: "override", Flag: "--description"})
if err != nil {
t.Fatal(err)
}
child := loaded.Config.Backends["local"]
if child.Endpoint != "https://overlay.invalid/v1" || child.Concurrency != 2 || child.QueueCapacity != 0 {
t.Fatalf("overlay inheritance and child override: %+v", child)
if info, ok := result.Metadata().Lookup(ck.Keys("context", "description")); !ok || info.Origin.Layer != ck.LayerCLI {
t.Fatalf("override origin = %+v", info)
}
if result.Config.Context.Description != "override" {
t.Fatalf("description = %q", result.Config.Context.Description)
}
found := false
for _, source := range result.Sources() {
if source.Layer == ck.LayerMain && source.ImportedFrom == nil {
context, ok := result.SourceContext(source.ID)
if !ok {
t.Fatal("main context missing")
}
data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, "fragment.yml"))
if err != nil || len(data) == 0 {
t.Fatalf("main context cannot access companion: %v", err)
}
found = true
}
}
if !found {
t.Fatal("main source missing")
}
if _, err := Load(ck.Input{Source: ck.File(filepath.Join(dir, "main.yml"))}, "missing"); err == nil {
t.Fatal("missing overlay accepted")
}
if _, err := Load(ck.Input{Source: ck.NoSource()}, "selected"); err == nil {
t.Fatal("overlay without context accepted")
}
}
func TestSiblingInheritanceDoesNotBypassBackendValidation(t *testing.T) {
func TestDiscoveryAndSelectedFailure(t *testing.T) {
first, second := t.TempDir(), t.TempDir()
search := ck.Searches(ck.SearchDirectory(first), ck.SearchDirectory(second))
load := func() (*ck.Result[Config], error) {
return Load(ck.Input{Source: ck.SearchConfig("audita", search)}, "")
}
result, err := load()
if err != nil {
t.Fatal(err)
}
for _, source := range result.Sources() {
if source.Layer == ck.LayerMain {
t.Fatalf("unexpected main source: %+v", source)
}
}
if err := os.WriteFile(filepath.Join(second, "config.yml"), []byte("context:\n description: selected\n"), 0644); err != nil {
t.Fatal(err)
}
result, err = load()
if err != nil {
t.Fatal(err)
}
if result.Config.Context.Description != "selected" {
t.Fatalf("description = %q", result.Config.Context.Description)
}
if err := os.WriteFile(filepath.Join(first, "config.yml"), []byte("version: 2\n"), 0644); err != nil {
t.Fatal(err)
}
if _, err := load(); err == nil {
t.Fatal("invalid selected file fell through")
}
}
func TestOverlayUsesMainDirectoryWithinWiderRoot(t *testing.T) {
root := t.TempDir()
dir := filepath.Join(root, "project")
if err := os.MkdirAll(filepath.Join(dir, "overlays"), 0755); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(dir, "config.yml"), []byte("version: 3\n"), 0644); err != nil {
t.Fatal(err)
}
if err := os.WriteFile(filepath.Join(dir, "overlays", "local.yml"), []byte("context:\n description: project\n"), 0644); err != nil {
t.Fatal(err)
}
result, err := Load(ck.Input{Source: ck.File(filepath.Join(dir, "config.yml")), Filesystem: &ck.FilesystemContext{Root: root}}, "local")
if err != nil {
t.Fatal(err)
}
if result.Config.Context.Description != "project" {
t.Fatalf("description = %q", result.Config.Context.Description)
}
}
func TestSchemaConstraintsAndExplicitValues(t *testing.T) {
path := filepath.Join(t.TempDir(), "config.yml")
for _, tc := range []struct {
name string
text string
name, text string
valid bool
}{
{
name: "invalid inherited parent setting",
text: `version: 2
backends:
base:
endpoint: https://base.invalid/v1
concurrency: 0
local:
extends: base
llm:
proposal_profile: proposal
`,
},
{
name: "invalid child override",
text: `version: 2
backends:
base:
endpoint: https://base.invalid/v1
concurrency: 3
local:
extends: base
concurrency: 0
llm:
proposal_profile: proposal
`,
},
{"nullable selections", "glossaries: null\nprotected_terms: []\nllm:\n validation_profile: null\n", true},
{"repeated modules", "pipeline:\n stages:\n - module: grammar\n - module: grammar\n", true},
{"removed backends", "backends: {}\n", false},
{"removed debug", "diagnostics:\n debug: true\n", false},
{"unknown module", "pipeline:\n stages:\n - module: unknown\n", false},
{"invalid chunk limit", "chunking:\n target_sections: 0\n", false},
{"null group", "llm: null\n", false},
{"zero budgets", "llm:\n transient_retries: 0\n repair_attempts: 0\n", true},
} {
t.Run(tc.name, func(t *testing.T) {
if _, err := loadText(tc.text, ""); err == nil {
t.Fatal("invalid backend concurrency accepted")
if err := os.WriteFile(path, []byte(tc.text), 0644); err != nil {
t.Fatal(err)
}
_, err := Load(ck.Input{Source: ck.File(path)}, "")
if (err == nil) != tc.valid {
t.Fatalf("load error: %v", err)
}
})
}
}
func TestOverridesFollowInheritance(t *testing.T) {
dir := t.TempDir()
path := filepath.Join(dir, "config.yml")
data := `glossary_collections:
common:
entries:
- id: a
name: First
category: character
derived:
extends: common
`
if err := os.WriteFile(path, []byte(data), 0644); err != nil {
t.Fatal(err)
}
result, err := Load(ck.Input{Source: ck.File(path)}, "", ck.Override{Path: ck.Keys("glossary_collections", "common", "entries"), Value: []any{map[string]any{"id": "a", "name": "Changed", "category": "character"}}, Flag: "--set"})
if err != nil {
t.Fatalf("%v: %+v", err, err.(*ck.LoadError).Diagnostics())
}
if got := result.Config.GlossaryCollections["derived"].Entries[0].Name; got != "First" {
t.Fatalf("inherited name = %q", got)
}
if got := result.Config.GlossaryCollections["common"].Entries[0].Name; got != "Changed" {
t.Fatalf("overridden name = %q", got)
}
}

Some files were not shown because too many files have changed in this diff Show More