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: matrix:
include: include:
- GO_IMAGE: golang:1.26.8-bookworm - GO_IMAGE: golang:1.27.4-bookworm
when: when:
- event: tag - event: tag
@@ -20,31 +20,33 @@ steps:
git check-ref-format "refs/tags/$${CI_COMMIT_TAG}" git check-ref-format "refs/tags/$${CI_COMMIT_TAG}"
git fetch origin "refs/tags/$${CI_COMMIT_TAG}: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}") 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}" test "$(printf '%s' "$${tag_commit}" | tr '[:upper:]' '[:lower:]')" = "$${expected_commit}"
git checkout --detach "$${tag_commit}" git checkout --detach "$${tag_commit}"
test "$(git rev-parse HEAD | tr '[:upper:]' '[:lower:]')" = "$${expected_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") bootstrap_dir=$(mktemp -d "$${CI_WORKSPACE%/*}/.releasekit-bootstrap.XXXXXX")
trap 'rm -rf "$${bootstrap_dir}"' EXIT 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 if [ -f go.sum ]; then
cp go.sum "$${bootstrap_dir}/go.sum" cp go.sum "$${bootstrap_dir}/releasekit.sum"
else else
: > "$${bootstrap_dir}/go.sum" : > "$${bootstrap_dir}/releasekit.sum"
fi fi
cp "$${bootstrap_dir}/go.mod" "$${bootstrap_dir}/releasekit.mod"
cp "$${bootstrap_dir}/go.sum" "$${bootstrap_dir}/releasekit.sum"
export GOWORK=off export GOWORK=off
export GOTOOLCHAIN=local 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 list -mod=mod -modfile="$${bootstrap_dir}/releasekit.mod" -m "$${releasekit_module}"
go build -mod=mod -modfile="$${bootstrap_dir}/releasekit.mod" \ go mod edit -modfile="$${bootstrap_dir}/releasekit.mod" -tool="$${releasekit_module}/cmd/releasekit"
-o "$${bootstrap_dir}/releasekit" "$${releasekit_module}/cmd/releasekit" go list -mod=mod -modfile="$${bootstrap_dir}/releasekit.mod" -deps "$${releasekit_module}/cmd/releasekit" > /dev/null
"$${bootstrap_dir}/releasekit" ci-deliver \ go tool -modfile="$${bootstrap_dir}/releasekit.mod" "$${releasekit_module}/cmd/releasekit" ci-deliver \
--repo "$${CI_WORKSPACE}" \ --repo "$${CI_WORKSPACE}" \
--prepared \ --prepared \
--commit "$${CI_COMMIT_SHA}" \ --commit "$${expected_commit}" \
"$${CI_COMMIT_TAG}" "$${CI_COMMIT_TAG}"

View File

@@ -1,55 +1,34 @@
# Audita # Audita
Audita polishes transcript JSON using glossary-aware and LLM-backed correction Audita polishes transcript JSON with glossary-aware and LLM-backed correction
modules. It validates proposed corrections and produces corrected text plus modules. It validates proposed edits and produces corrected text and reports for
reports for review and subprocess integration. review or subprocess integration.
## Quickstart ## Quickstart
From a checkout, build with Go 1.26.0 or newer: Build with Go 1.27.0 or newer:
```sh ```sh
go build -o ./bin/audita ./cmd/audita go build -o ./bin/audita ./cmd/audita
``` ```
Processing requires a reachable [compatible LLM endpoint](docs/integrations/openai-compatible-llm.md) Edit the synthetic endpoint and model in [examples/local/prompts.yml](examples/local/prompts.yml)
and access to a model you select. The [minimal config](examples/minimal-config.yml) for a reachable OpenAI-compatible service. From `examples/local`, run the built
targets an unauthenticated local endpoint; edit its endpoint and executable (adjust the executable path if needed):
[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:
```sh ```sh
./bin/audita config validate --config examples/minimal-config.yml ../../bin/audita config validate --config config.yml
./bin/audita config print-effective --config examples/minimal-config.yml --view profiles ../../bin/audita process --config config.yml --output corrected.json transcript.json
``` ```
Run the included small input with the minimal config: 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)
```sh includes service, overlay, prompt editing, preview, and shared glossary projects.
./bin/audita process examples/tiny-transcript.json \ See the [v3 migration guide](docs/migrations/v3.md) for the configuration cutover.
--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.
## Documentation ## Documentation
- [CLI reference](docs/cli.md) - [CLI reference](docs/cli.md) and [configuration](docs/config.md)
- [Configuration and maintained examples](docs/config.md)
- [Operations and artifact lifecycle](docs/operations.md) - [Operations and artifact lifecycle](docs/operations.md)
- [Transcript and glossary inputs](docs/integrations/transcript-glossary-files.md) - [Transcript and glossary inputs](docs/integrations/transcript-glossary-files.md)
- [Output files and report formats](docs/integrations/output-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 ( import (
"context" "context"
"io"
"os" "os"
"os/signal" "os/signal"
"syscall" "syscall"
"gitea.maximumdirect.net/eric/audita/v3/internal/cli" "gitea.maximumdirect.net/eric/audita/v4/internal/cli"
) )
func main() { 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) ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop() 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 package main
import ( import (
"bufio"
"bytes" "bytes"
"context" "context"
"encoding/json" "encoding/json"
"errors"
"fmt" "fmt"
"io"
"net/http" "net/http"
"net/http/httptest" "net/http/httptest"
"os" "os"
"os/exec" "os/exec"
"os/signal"
"path/filepath" "path/filepath"
"reflect" "reflect"
"strconv" "strconv"
@@ -19,10 +21,10 @@ import (
"testing" "testing"
"time" "time"
"gitea.maximumdirect.net/eric/audita/v3/internal/cli" "gitea.maximumdirect.net/eric/audita/v4/internal/cli"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/reporting" "gitea.maximumdirect.net/eric/audita/v4/internal/core/reporting"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema" "gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
"gopkg.in/yaml.v3" "go.yaml.in/yaml/v4"
) )
func TestProcessSubprocessHelper(t *testing.T) { func TestProcessSubprocessHelper(t *testing.T) {
@@ -38,10 +40,7 @@ func TestProcessSubprocessHelper(t *testing.T) {
} }
syscall.Umask(int(mask)) syscall.Umask(int(mask))
} }
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) os.Exit(run(os.Args[i+1:], os.Stdout, os.Stderr))
code := cli.Run(ctx, os.Args[i+1:], os.Stdout, os.Stderr)
stop()
os.Exit(code)
} }
} }
os.Exit(2) 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) { 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) w.WriteHeader(http.StatusInternalServerError)
_, _ = fmt.Fprintf(w, `{"error":{"message":"provider echoed %s"}}`, p.secret) _, _ = io.WriteString(w, `{"error":{"message":"provider unavailable"}}`)
return 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 p.mode == "repair-filter-later-failure" && !validation {
if proposalCall == 1 { if proposalCall == 1 {
content = `{"wrong":true}` content = `{"wrong":true}`
} else { } 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-") { if strings.HasPrefix(p.mode, "span-") {
switch p.mode { switch p.mode {
case "span-clean", "span-filter": 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" { 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": 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": 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 validation {
if p.mode == "span-clean" || p.mode == "span-filter" { 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 { } 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 { 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 { 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" { 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-") { 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 p.mode == "invalid-decision-after-repair" {
if validationCall == 1 { if validationCall == 1 {
content = `{"wrong":true}` content = `{"wrong":true}`
} else { } 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 continue
} }
approved := !(p.mode == "decision-mixed" && len(requestedIndices) == 4 && index == 2) 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 { 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 { 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}) raw, _ := json.Marshal(map[string]any{"validations": decisions})
content = string(raw) content = string(raw)
@@ -191,27 +198,37 @@ 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) _, _ = 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 { func fixtureValidationIndices(messages []struct {
Content string `json:"content"` Content string `json:"content"`
}) ([]int, error) { }) ([]int, error) {
for _, message := range messages { for _, message := range messages {
const marker = "Corrections to validate:" if items, ok := fixtureValidationItems(message.Content); ok {
position := strings.LastIndex(message.Content, marker)
if position < 0 {
continue
}
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)) indices := make([]int, len(items))
for i, item := range items { for i, item := range items {
indices[i] = item.CorrectionIndex indices[i] = item.CorrectionIndex
} }
return indices, nil return indices, nil
} }
}
return nil, fmt.Errorf("validation request items not found") return nil, fmt.Errorf("validation request items not found")
} }
@@ -221,7 +238,6 @@ type processFixture struct {
dir string dir string
config string config string
transcript string transcript string
glossary string
output string output string
provider *fixtureProvider provider *fixtureProvider
server *httptest.Server 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)} p := &fixtureProvider{mode: mode, secret: `selected-secret-"\-123`, entered: make(chan struct{}, 1)}
server := httptest.NewServer(http.HandlerFunc(p.serve)) server := httptest.NewServer(http.HandlerFunc(p.serve))
t.Cleanup(server.Close) 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) 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") configPath := filepath.Join(dir, "config.yml")
repairs := 0 repairs := 0
if mode == "repair-filter-later-failure" || mode == "invalid-decision-after-repair" { 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-") { if strings.HasPrefix(mode, "span-") || strings.HasPrefix(mode, "decision-") {
repairs = 1 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-") { 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" 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 { if err := os.WriteFile(transcript, []byte(`[{"id":1,"speaker":"A","start":0,"end":1,"text":"hello world"}]`), 0600); err != nil {
t.Fatal(err) 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 { return processFixture{dir: dir, config: configPath, transcript: transcript,
t.Fatal(err)
}
return processFixture{dir: dir, config: configPath, transcript: transcript, glossary: glossary,
output: filepath.Join(dir, "output.json"), provider: p, server: server} output: filepath.Join(dir, "output.json"), provider: p, server: server}
} }
func (f processFixture) run(t *testing.T, includeOutput bool, extra ...string) (int, string, string) { func (f processFixture) run(t *testing.T, includeOutput bool, extra ...string) (int, string, string) {
t.Helper() 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 { if includeOutput {
args = append(args, "--output", f.output) 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() 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 { func (f processFixture) errors(t *testing.T) reporting.ErrorsDocument {
t.Helper() t.Helper()
raw, err := os.ReadFile(filepath.Join(f.dir, "errors.yml")) 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 { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
transcript, err := schema.ParseTranscriptJSON(raw) transcript, err := schema.ParseSourceTranscriptJSON(raw)
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
return transcript return transcript.Canonical()
} }
func (f processFixture) debugArtifacts(t *testing.T) (*schema.Transcript, []map[string]json.RawMessage) { 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) 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) { func TestSubprocessFiltersBlankResultAlongsideApprovedCorrections(t *testing.T) {
f := newProcessFixture(t, "span-filter", "[spoken_word]") f := newProcessFixture(t, "span-filter", "[spoken_word]")
f.setSegments(t, "uh hello", "I I think", "uh") f.setSegments(t, "uh hello", "I I think", "uh")
@@ -775,7 +805,7 @@ func TestSubprocessRespectsNegativeMeaningReviewOnDeletion(t *testing.T) {
func TestSubprocessDefaultFileOutputAndReports(t *testing.T) { func TestSubprocessDefaultFileOutputAndReports(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]") f := newProcessFixture(t, "normal", "[grammar]")
code, stdout, stderr := f.run(t, true) 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) t.Fatalf("code=%d stdout=%q stderr=%q", code, stdout, stderr)
} }
output, err := os.ReadFile(f.output) output, err := os.ReadFile(f.output)
@@ -807,7 +837,7 @@ func TestSubprocessStdoutAndSelectedReportDirectory(t *testing.T) {
t.Fatal(err) t.Fatal(err)
} }
code, stdout, stderr := f.run(t, false, "--report-dir", reports) 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) t.Fatalf("code=%d stdout=%q stderr=%q", code, stdout, stderr)
} }
if _, err := os.Stat(f.output); !os.IsNotExist(err) { if _, err := os.Stat(f.output); !os.IsNotExist(err) {
@@ -830,7 +860,7 @@ func TestSubprocessUsesIndependentTranscriptReportAndDebugDestinations(t *testin
} }
f.output = filepath.Join(transcriptDir, "corrected.json") f.output = filepath.Join(transcriptDir, "corrected.json")
code, stdout, stderr := f.run(t, true, "--report-dir", reportDir, "--debug", "--work-dir", debugDir) 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) 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")) { 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}, {false, false}, {false, true}, {true, false}, {true, true},
} { } {
f := newProcessFixture(t, "normal", "[grammar]") 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") reportDir := filepath.Join(f.dir, "missing")
extra := []string{"--reporting=false", "--report-dir", reportDir} extra := []string{"--verbose", "--reporting=false", "--report-dir", reportDir}
if selection.reporting { if selection.reporting {
reportDir = filepath.Join(f.dir, "selected-reports") reportDir = filepath.Join(f.dir, "selected-reports")
if err := os.Mkdir(reportDir, 0700); err != nil { if err := os.Mkdir(reportDir, 0700); err != nil {
t.Fatal(err) t.Fatal(err)
} }
extra = []string{"--reporting=true", "--report-dir", reportDir} extra = []string{"--verbose", "--reporting=true", "--report-dir", reportDir}
} }
if selection.debug { if selection.debug {
extra = append(extra, "--debug") extra = append(extra, "--debug")
} }
code, stdout, stderr := f.run(t, true, extra...) 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) t.Fatalf("selection=%+v code=%d stdout=%q stderr=%q", selection, code, stdout, stderr)
} }
output, err := os.ReadFile(f.output) output, err := os.ReadFile(f.output)
if err != nil { if err != nil {
t.Fatal(err) 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 == "" { if expectedOutput == "" {
expectedOutput, expectedSummary = string(output), summary expectedOutput, expectedSummary = string(output), summary
} else if string(output) != expectedOutput || summary != expectedSummary { } else if string(output) != expectedOutput || summary != expectedSummary {
@@ -916,31 +938,7 @@ func TestSubprocessReportingAndDebugSelections(t *testing.T) {
t.Fatal(err) 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) { func TestSubprocessAllModelFailureStillCompletes(t *testing.T) {
f := newProcessFixture(t, "all-model-failure", "[grammar, grammar]") 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") { if code != 0 || stdout != "" || !strings.Contains(stderr, "2 work units with errors") {
t.Fatalf("code=%d stdout=%q stderr=%q", code, stdout, stderr) 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 { 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) 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) { func TestSubprocessAllValidationFailureStillCompletes(t *testing.T) {
f := newProcessFixture(t, "all-validation-failure", "[grammar, grammar]") 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") { if code != 0 || stdout != "" || !strings.Contains(stderr, "2 work units with errors") {
t.Fatalf("code=%d stdout=%q stderr=%q", code, stdout, stderr) 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) { func TestSubprocessRecoveredFilteringSurvivesLaterFailure(t *testing.T) {
f := newProcessFixture(t, "repair-filter-later-failure", "[grammar, grammar]") 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") { 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)) 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) { func TestSubprocessRepairedInvalidDecisionsRemainAnError(t *testing.T) {
f := newProcessFixture(t, "invalid-decision-after-repair", "[grammar]") 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") { if code != 0 || !strings.Contains(stderr, "0 corrections applied; 1 work units with errors; 0 recoveries") {
t.Fatalf("code=%d stderr=%q", code, stderr) t.Fatalf("code=%d stderr=%q", code, stderr)
} }
@@ -1037,7 +1064,7 @@ func TestSubprocessCancellationLeavesFailedReportsWithoutTranscript(t *testing.T
f := newProcessFixture(t, "wait-cancel", "[grammar, grammar]") f := newProcessFixture(t, "wait-cancel", "[grammar, grammar]")
ctx, stop := context.WithTimeout(context.Background(), 5*time.Second) ctx, stop := context.WithTimeout(context.Background(), 5*time.Second)
defer stop() 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 := exec.CommandContext(ctx, os.Args[0], args...)
command.Env = append(os.Environ(), "AUDITA_HELPER_PROCESS=1", "AUDITA_TEST_PROVIDER_KEY="+f.provider.secret) command.Env = append(os.Environ(), "AUDITA_HELPER_PROCESS=1", "AUDITA_TEST_PROVIDER_KEY="+f.provider.secret)
var stderr bytes.Buffer var stderr bytes.Buffer
@@ -1054,8 +1081,9 @@ func TestSubprocessCancellationLeavesFailedReportsWithoutTranscript(t *testing.T
t.Fatal(err) t.Fatal(err)
} }
err := command.Wait() err := command.Wait()
if ctx.Err() != nil || err == nil { var exit *exec.ExitError
t.Fatalf("cancellation did not stop run: %v %v stderr=%q", err, ctx.Err(), stderr.String()) 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 { if document := f.errors(t); document.Status != reporting.StatusFailed || len(document.Errors) == 0 {
t.Fatalf("cancellation report: %+v", document) t.Fatalf("cancellation report: %+v", document)
@@ -1067,7 +1095,7 @@ func TestSubprocessCancellationLeavesFailedReportsWithoutTranscript(t *testing.T
func TestSubprocessPartialValidationAndLaterStage(t *testing.T) { func TestSubprocessPartialValidationAndLaterStage(t *testing.T) {
f := newProcessFixture(t, "partial-validation", "[grammar, grammar]") 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") { if code != 0 || !strings.Contains(stderr, "1 corrections applied; 1 work units with errors") {
t.Fatalf("code=%d stderr=%q", code, stderr) 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]") f := newProcessFixture(t, "normal", "[grammar]")
if err := os.WriteFile(f.transcript, []byte("not JSON"), 0600); err != nil { if err := os.WriteFile(f.transcript, []byte("not JSON"), 0600); err != nil {
t.Fatal(err) t.Fatal(err)
} }
code, _, _ := f.run(t, true) 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()) 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) { if _, err := os.Stat(f.output); !os.IsNotExist(err) {
t.Fatalf("failed transcript published: %v", 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) { func TestSubprocessMissingInheritanceParentFailsBeforeProviderDispatch(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]") f := newProcessFixture(t, "normal", "[grammar]")
original, err := os.ReadFile(f.config) original, err := os.ReadFile(filepath.Join(f.dir, "prompts.yml"))
if err != nil { if err != nil {
t.Fatal(err) 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) { if updated == string(original) {
t.Fatal("process fixture backend configuration was not found") 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) t.Fatal(err)
} }
code, stdout, stderr := f.run(t, true) 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()) 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]") f := newProcessFixture(t, "normal", "[grammar]")
if err := os.WriteFile(f.transcript, []byte("not JSON"), 0600); err != nil { if err := os.WriteFile(f.transcript, []byte("not JSON"), 0600); err != nil {
t.Fatal(err) t.Fatal(err)
@@ -1139,25 +1153,13 @@ func TestSubprocessInvalidInputWritesFailedReportsToSelectedDirectory(t *testing
t.Fatal(err) t.Fatal(err)
} }
code, _, _ := f.run(t, true, "--report-dir", reportDir) 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()) t.Fatalf("invalid input dispatched: code=%d calls=%d", code, f.provider.callCount())
} }
raw, err := os.ReadFile(filepath.Join(reportDir, "errors.yml")) for _, name := range []string{"errors.yml", "recoveries.yml", "report.md"} {
if err != nil { if _, err := os.Stat(filepath.Join(reportDir, name)); !os.IsNotExist(err) {
t.Fatal(err) t.Fatalf("report created before preflight: %s %v", name, 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)
} }
if _, err := os.Stat(filepath.Join(f.dir, "errors.yml")); !os.IsNotExist(err) { if _, err := os.Stat(filepath.Join(f.dir, "errors.yml")); !os.IsNotExist(err) {
t.Fatalf("failed report appeared in default directory: %v", 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) { func TestSubprocessOptionalDebugFailureDoesNotChangeOutcome(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]") f := newProcessFixture(t, "normal", "[grammar]")
code, _, stderr := f.run(t, true, "--debug", "--work-dir", f.transcript) 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) t.Fatalf("optional debug failure changed processing: code=%d stderr=%q", code, stderr)
} }
if _, err := os.Stat(f.output); err != nil { if _, err := os.Stat(f.output); err != nil {
@@ -1197,11 +1199,63 @@ func TestSubprocessTranscriptPreflightWithoutReporting(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]") f := newProcessFixture(t, "normal", "[grammar]")
f.output = filepath.Join(f.dir, "missing", "output.json") f.output = filepath.Join(f.dir, "missing", "output.json")
code, _, stderr := f.run(t, true, "--reporting=false") 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) 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) { func TestSubprocessOutputPermissionsHonorUmask(t *testing.T) {
for _, mask := range []string{"0077", "0022"} { for _, mask := range []string{"0077", "0022"} {
t.Run(mask, func(t *testing.T) { 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} { for _, fail := range []bool{false, true} {
t.Run(fmt.Sprint(fail), func(t *testing.T) { t.Run(fmt.Sprint(fail), func(t *testing.T) {
f := newProcessFixture(t, "normal", "[]") f := newProcessFixture(t, "normal", "[]")
selected, unused := "selected-path-secret", "unused-path-secret" reportDir := filepath.Join(f.dir, "reports")
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)
if err := os.Mkdir(reportDir, 0700); err != nil { if err := os.Mkdir(reportDir, 0700); err != nil {
t.Fatal(err) t.Fatal(err)
} }
f.output = filepath.Join(reportDir, "out.json") f.output = filepath.Join(reportDir, "out.json")
debugParent := filepath.Join(f.dir, selected) debugParent := filepath.Join(f.dir, "diagnostics")
if fail { if fail {
if err := os.WriteFile(f.transcript, []byte("invalid"), 0600); err != nil { if err := os.WriteFile(f.transcript, []byte("invalid"), 0600); err != nil {
t.Fatal(err) t.Fatal(err)
} }
} }
code, _, stderr := f.run(t, true, "--debug", "--work-dir", debugParent) 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) t.Fatalf("code=%d stderr=%q", code, stderr)
} }
if strings.Contains(stderr, selected) || strings.Contains(stderr, unused) { if !fail && (!strings.Contains(stderr, filepath.Join(reportDir, "report.md")) || !strings.Contains(stderr, debugParent)) {
t.Fatalf("credential in stderr: %q", stderr) t.Fatalf("missing destination announcement: %q", stderr)
} }
if !strings.Contains(stderr, "[REDACTED]") { if _, err := os.Stat(filepath.Join(reportDir, "report.md")); !fail && err != nil {
t.Fatalf("missing redacted announcement: %q", stderr)
}
if _, err := os.Stat(filepath.Join(reportDir, "report.md")); err != nil {
t.Fatal(err) t.Fatal(err)
} }
dirs, err := os.ReadDir(debugParent) 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) t.Fatalf("debug location: %v %v", dirs, err)
} }
if !fail { if !fail {
@@ -1303,7 +1343,7 @@ func TestSubprocessPathAnnouncementsAreRedacted(t *testing.T) {
func TestSubprocessInteractionWriteFailureIsVisibleAndNonfatal(t *testing.T) { func TestSubprocessInteractionWriteFailureIsVisibleAndNonfatal(t *testing.T) {
f := newProcessFixture(t, "normal", "[grammar]") f := newProcessFixture(t, "normal", "[grammar]")
code, _, baselineSummary := f.run(t, true) code, _, baselineSummary := f.run(t, true, "--verbose")
if code != 0 { if code != 0 {
t.Fatal(baselineSummary) t.Fatal(baselineSummary)
} }
@@ -1318,16 +1358,16 @@ func TestSubprocessInteractionWriteFailureIsVisibleAndNonfatal(t *testing.T) {
t.Errorf("debug directory: %v %v", dirs, err) t.Errorf("debug directory: %v %v", dirs, err)
return 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) t.Error(err)
} }
} }
f.provider.mu.Unlock() f.provider.mu.Unlock()
code, _, stderr := f.run(t, true, "--debug") 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) 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) t.Fatalf("missing debug failures: %q", stderr)
} }
output, err := os.ReadFile(f.output) output, err := os.ReadFile(f.output)
@@ -1360,7 +1400,7 @@ func TestSubprocessInPlaceTranscript(t *testing.T) {
t.Fatal(err) t.Fatal(err)
} }
if invalid { 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) t.Fatalf("failed processing changed input: code=%d %s", code, stderr)
} }
} else if code != 0 || stdout != "" || !bytes.Contains(after, []byte("Hello world")) { } else if code != 0 || stdout != "" || !bytes.Contains(after, []byte("Hello world")) {
@@ -1374,15 +1414,18 @@ func TestSubprocessProfileSources(t *testing.T) {
f := newProcessFixture(t, "success", "[]") f := newProcessFixture(t, "success", "[]")
// PromptKit uses profile IDs, not filename stems. A report-named profile is // PromptKit uses profile IDs, not filename stems. A report-named profile is
// still an input and must not be overwritten during report initialization. // still an input and must not be overwritten during report initialization.
loaded := filepath.Join(f.dir, "profiles", "errors.yml") if err := os.Mkdir(filepath.Join(f.dir, "prompts"), 0700); err != nil {
if err := os.Rename(filepath.Join(f.dir, "profiles", "proposal.yaml"), loaded); 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) t.Fatal(err)
} }
before, err := os.ReadFile(loaded) before, err := os.ReadFile(loaded)
if err != nil { if err != nil {
t.Fatal(err) 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") code, _, stderr := f.run(t, true, "--reporting=false")
if code != 0 { if code != 0 {
t.Fatalf("unused alternate rejected: %d %s", code, stderr) t.Fatalf("unused alternate rejected: %d %s", code, stderr)
@@ -1396,12 +1439,12 @@ func TestSubprocessProfileSources(t *testing.T) {
if err != nil { if err != nil {
t.Fatal(err) 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) t.Fatalf("loaded profile not protected: %d %s", code, stderr)
} }
parentDir := filepath.Join(f.dir, "profiles", "catalog") parentDir := filepath.Join(f.dir, "prompts", "catalog")
childDir := filepath.Join(f.dir, "profiles", "nested", "child") childDir := filepath.Join(f.dir, "prompts", "nested", "child")
for _, directory := range []string{parentDir, childDir} { for _, directory := range []string{parentDir, childDir} {
if err := os.MkdirAll(directory, 0700); err != nil { if err := os.MkdirAll(directory, 0700); err != nil {
t.Fatal(err) t.Fatal(err)
@@ -1411,8 +1454,8 @@ func TestSubprocessProfileSources(t *testing.T) {
child := filepath.Join(childDir, "override.yaml") child := filepath.Join(childDir, "override.yaml")
resource := filepath.Join(parentDir, "report.md") resource := filepath.Join(parentDir, "report.md")
for path, content := range map[string]string{ 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", 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 literal/~child:\n extends: source\n", child: "prompts:\n - id: child\n extends: {id: source}\n",
resource: "Captured operator message.\n", resource: "Captured operator message.\n",
} { } {
if err := os.WriteFile(path, []byte(content), 0600); err != nil { if err := os.WriteFile(path, []byte(content), 0600); err != nil {
@@ -1429,7 +1472,7 @@ func TestSubprocessProfileSources(t *testing.T) {
if err != nil { if err != nil {
t.Fatal(err) 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) 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 { if err != nil {
t.Fatal(err) 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) 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) — - [ADR 0001: Adopt ReleaseKit for release management](0001-releasekit.md) —
accepted 2026-10-07. 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 Use the
[documentation policy's ADR lifecycle](../policy/documentation.md#architecture-decision-records) [documentation policy's ADR lifecycle](../policy/documentation.md#architecture-decision-records)

View File

@@ -1,116 +1,53 @@
# Audita CLI Reference # Audita CLI Reference
The shared version-2 configuration parser and offline profile inspection serve Audita uses CommandKit for routing and the ConfigKit and PromptKit integrations
`process`, `config validate`, and `config print-effective`. for their standard inspection and request commands. Run `audita --help` or
The [configuration reference](config.md) owns fields, defaults, and validation; command-specific `--help` for the installed command inventory. The adopted
the [migration guide](migrations/v2.md) maps retired inputs. [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 ```sh
audita process <transcript.json> --glossary <glossary.yml> [flags] audita process [flags] transcript.json
audita config validate --config <config.yml> [flags]
audita config print-effective [flags]
audita version
``` ```
Root invocation, `--help`, `-h`, and command help succeed without loading a config `--config` selects a main configuration and `--overlay` selects its overlay.
file or resolving secrets. Unknown commands and flags return exit code `2`. `--output` writes the transcript to a file; omission selects stdout. The shared
`process` accepts exactly one transcript path, either before the flags or after `--debug` flag enables retained debug artifacts, and `--quiet` suppresses optional
them. With flags first, put the transcript last. Both config commands reject messages. Quiet processing requires an output file or `/dev/null`. See
positional arguments and process-only flags. [operations](operations.md) for output and report lifecycle.
All three commands accept `--config <path>` and `--overlay <name>`. `config validate` Progress for processing goes to stderr. Use `--progress` to show stage and
requires an explicit nonempty `--config`; the other commands select the explicit chunk activity, model proposal, validation and repair operations, and observed
file, then `/usr/local/etc/audita/config.yml`, then `/etc/audita/config.yml`. counts as work completes. Debug mode enables progress by default.
Missing system candidates are skipped; inaccessible selected files are errors. `--progress=false` disables it, and quiet mode suppresses it even when
No file means a configuration error. `AUDITA_CONFIG` is ignored. The selected `--progress` is explicit.
overlay is loaded beside the main file, not used to locate profile files.
`audita version` prints `audita <version>` and a newline to stdout, with no Explicit process flags override root settings only. `--glossaries` and
application configuration or provider setup. It returns `0` on success with `--protected-terms` each accept one JSON array of collection names or `null`;
empty stderr. `help version`, `version -h`, and `version --help` print command `[]` clears the selection. Set pipeline order and per-entry overrides in YAML.
usage to stdout and return `0`. Help follows standard flag parsing and can Other supplied flags cover profiles, output schema, description, reporting,
short-circuit trailing arguments. Other invalid invocations return `2` with a chunking, normalization, validation budget, and debug
usage error on stderr. The command uses ReleaseKit's public work directory. `audita process --help` lists the available flags. An omitted flag
`buildinfo.Version()` accessor. It reports an injected release identifier when does not contribute an override. [Configuration](config.md) defines their values
present, otherwise the executable's main-module version when available and not and inheritance.
`(devel)`, and `dev` when neither source provides a release identifier.
## Setting overrides ## Inspection and outcomes
Only flags actually supplied override file or overlay settings. `--modules ''` The application configuration scope uses ConfigKit's native effective values,
clears the module pipeline, and an explicit numeric zero reaches configuration source evidence, explanation, comparison, and redaction. PromptKit supplies its
validation. The shared setting flags are: 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 | Process stdout contains transcript JSON when no output file is selected. Ordinary
| --- | --- | reports may record recoverable model failures even when processing completes.
| Profile selection | `--proposal-profile`, `--validation-profile` | Exit status `0` means success, `1` runtime or output failure, `2` invalid usage
| Pipeline and output | `--modules`, `--output-schema` | or input, and native comparison may return `3` for differences. A missing
| Validation budget | `--validation-max-prompt-tokens` | processing profile or required glossary selection is an input failure. See the
| Chunking | `--target-sections`, `--max-section-tokens`, `--min-section-tokens` | [output contract](integrations/output-files.md) and [subprocess contract](integrations/subprocess.md).
| 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.

View File

@@ -1,192 +1,114 @@
# Audita Configuration # Audita Configuration
This reference describes the version-2 configuration loader in `internal/core/config`. Audita uses version 3 application configuration. See the [migration guide](migrations/v3.md)
Use the maintained [local](../examples/minimal-config.yml) and and [examples](../examples/) for complete projects. Command syntax is owned by
[service](../examples/production-config.yml) examples with their separately [the CLI reference](cli.md).
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.
## Loading and precedence ## Loading and composition
The application selects one main YAML file: an explicit `--config`, then An explicit `--config` selects one main YAML file. Without it, ConfigKit searches
`/usr/local/etc/audita/config.yml` if present, then `/etc/audita/config.yml` the working directory, user configuration directory, and Unix system directories
if present. Missing system candidates are skipped; an explicit missing or empty for `audita` configuration. If no file is found, built-in defaults apply. An
path, inaccessible selected file, or absence of any selected file is an error. explicit invalid selection or failure of a selected file is an error; search does
`config validate` requires an explicit file. ConfigKit loads built-in defaults, not continue after a selected file fails. An omitted version uses the v3 schema;
the selected file, an optional named overlay from `overlays/<name>.yml` beside the a supplied version must be `3`.
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.
After overlay and explicit CLI override precedence is applied, ConfigKit resolves Operator sources may use ConfigKit imports. The selected main file provides the
native sibling inheritance before typed decoding. Any input mapping may use base for an optional `overlays/<name>.yml`, optional `glossary.yml`, and recursive
`extends: <sibling-name>`; the child keeps its key, inherits parent settings, and `glossary/` YAML files. Without a main source, automatic companion files are not
overrides them with its own settings. Selected overlay and CLI values therefore loaded from the working directory. ConfigKit composes sources, resolves native
participate in inheritance at their normal precedence. The generic syntax and inheritance, applies explicit overrides, records derived defaults, and validates
resolution rules are defined by ConfigKit v0.7.1's the result. Its [configuration reference](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md)
[sibling inheritance contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/docs/config.md#sibling-inheritance). owns native composition and provenance semantics.
`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.
### PromptKit profiles and operator prompts ### PromptKit profiles and operator prompts
`profiles_dir` selects a PromptKit configuration root, resolved against the PromptKit loads its default catalog and Audita's embedded prompts, followed by
selected main file's directory unless it is absolute. The root may contain optional `prompts.yml` and recursive `prompts/` YAML files beside the application
keyed `profiles`, `backends`, and `prompts` definitions; it is not limited to main. Native imports, resource collections, inheritance, and replacement apply.
profile-only files. IDs come from literal YAML mapping keys, never filenames. Profiles, backends, models, credentials, admission, and provider parameters belong
Multiple definitions may share a document, and a document may contribute to any to PromptKit configuration; see its [format reference](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.0/docs/formats.md).
of the supported mappings. Directory discovery is recursive, but discovery The engine captures its sources for an invocation. Edit files and run a new
order does not establish field precedence. Contributions within each source invocation to pick up changes. Inspection does not require model credentials.
group must compose without conflicting values.
PromptKit assembles sources in this order: its selected catalogs and owned ## Pipeline and glossary selections
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.
Both selected roles must resolve to an existing profile, registered backend, `glossary_collections` maps names to collections with an ordered `entries` list.
nonblank effective model, and nonblank endpoint. The normalized effective Each entry has an `id`, `name`, and `category`; `description`, `aliases`, and
endpoint must match the application backend endpoint. A selected profile cannot `plural` provide optional context. Entries are identified within their collection
introduce a competing `api_key_env` lookup; the application backend credential by `id`. Root `glossaries` and `protected_terms` select collection names. If root
supplies the runtime key when required. Other unselected profiles may be protection is omitted, it derives from the root glossary selection.
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.
Profile IDs and parent IDs are exact, literal keys. PromptKit profiles can use `pipeline.stages` is an ordered list of `module` records; supported modules are
native `extends` inheritance; child fields override inherited fields, while `glossary`, `homophones`, `spoken_word`, and `grammar`. The default sequence is
unmentioned controls survive changes to model or backend. For example: `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 Each entry receives its selected context and independent protection. Glossary
profiles: correction exempts active recognized spellings from protection for that entry.
"shared~base": A longer exempt name still takes precedence over a shorter protected spelling
backend: service inside it. A glossary correction must have at least one selected entry at
model: example-model processing preflight. Empty definitions and empty protection remain valid
temperature: 0.4 configuration.
top_p: 0.8
"proposal fast":
extends: "shared~base"
model: faster-model
temperature: 0
```
Presence matters. Explicit `temperature: 0` is sent as zero; omission leaves it The bundled prompts use English. The modules request complementary work:
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.
Operator documents can also override an embedded prompt/version, including its - `glossary`: context-supported corrections toward selected glossary terms.
messages and definition-level output settings. Shared variables supplied by the - `homophones`: plausible spoken-word mistranscriptions, including glossary terms.
adapter are rendered only when an effective message references them; Audita does - `spoken_word`: conservative filler, hesitation, and accidental repetition cleanup.
not append omitted shared text. Audita's per-call schemas, structural repair - `grammar`: punctuation, capitalization, spacing, and whole-word `a`/`an` cleanup.
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.
### Migrating PromptKit profile documents Otherwise acceptable minor editorial cleanup may be accepted across modules, as
specified by the [editorial acceptance boundary](policy/architecture.md#correction-and-concurrency-invariants).
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.
## Settings ## Settings
| Field | Default | Rule | | Setting | Default | Meaning |
| --- | --- | --- | | --- | --- | --- |
| `profiles_dir` | `profiles` | Nonempty PromptKit document root; resolved relative to the selected main file, or absolute. | | `llm.proposal_profile` | unset | PromptKit profile for proposals; required for processing entries. |
| `backends.<id>.endpoint` | None | Required nonempty endpoint for each backend. At least one backend is required. | | `llm.validation_profile` | effective proposal profile | Profile for model validation; null clears a selection before fallback. |
| `backends.<id>.concurrency` | `1` | Positive finite capacity; shared by both roles using that backend. | | `llm.correction_repair_profile` | effective proposal profile | Profile for correction repair; null clears an inherited selection before fallback. |
| `backends.<id>.queue_capacity` | `1024` | Nonnegative; zero disables waiting admission. | | `llm.correction_repair_attempts` | `1` | Nonnegative repair attempts per correction; zero disables correction repair. |
| `backends.<id>.credential` | Unset | Optional environment-variable secret reference; omission or null means unauthenticated use. | | `llm.transient_retries` | `2` | Additional transient attempts per generation. |
| `llm.proposal_profile` | None | Required nonempty profile ID. | | `llm.repair_attempts` | `2` | Structural repairs, from zero through three. |
| `llm.validation_profile` | Final proposal profile | Omission inherits the final proposal selection; explicit empty or null fails. | | `llm.operation_timeout` | `15m` | Positive duration per logical operation. |
| `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). |
| `validation.max_prompt_tokens` | `2048` | Positive validation batching budget. | | `validation.max_prompt_tokens` | `2048` | Positive validation batching budget. |
| `chunking.target_sections` | Unset | Optional positive target; omission or null selects automatic chunking. | | `context.description` | empty | Prompt context; at most 500 bytes after trimming. |
| `chunking.max_section_tokens` | `8192` | Positive maximum estimate. | | `chunking.target_sections` | unset | Optional positive count. Processing requires exactly this many nonempty sections when specified. An infeasible count is an input error. |
| `chunking.min_section_tokens` | `2048` | Positive and no greater than maximum. | | `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` | `4.0` | Nonnegative numeric seconds. | | `normalization.max_segment_gap`, `normalization.ellipsis_gap` | `4`, `3.5` | Nonnegative seconds. |
| `normalization.ellipsis_gap` | `3.5` | Nonnegative numeric seconds. | | `normalization.max_segment_duration`, `normalization.max_segment_tokens` | `60`, `2048` | Positive seconds and token estimate. |
| `normalization.max_segment_duration` | `60.0` | Positive numeric seconds. | | `output.schema` | `bare-segments` | Output format; see [output contracts](integrations/output-files.md). |
| `normalization.max_segment_tokens` | `2048` | Positive token estimate. | | `reporting.enabled`, `reporting.stdout_dir` | `true`, `.` | Ordinary report capture and default directory for stdout output. |
| `thresholds.glossary`, `.homophones`, `.spoken_word`, `.grammar` | `0.8` each | Confidence thresholds in `[0, 1]`. | | `diagnostics.work_dir` | `/tmp/audita` | Parent directory for optional debug capture. |
| `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. |
Module keys select correction modules; validator chains remain built into them. For example, an entry can disable correction repair or select another profile:
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.
## 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 Processing profiles are selected explicitly; no profile or glossary is selected
variable name, such as `credential: AUDITA_SERVICE_KEY`. Every reference that automatically. The validation selection falls back after root and per-entry
survives overlay and override resolution must name a set, nonempty variable, settings are combined. An explicit root correction repair profile is inherited
including credentials on backends unused by the selected roles. A replacement by each entry unless overridden or cleared with null; otherwise the entry uses
reference resolves only the replacement; null removes the reference. General its effective proposal profile. The repair profile is checked only when its
`AUDITA_*` and `OPENROUTER_API_KEY` variables have no implicit setting effect. attempt budget is positive. Each correction repair attempt is a logical call
Secret values are available to the runtime through the resolved reference, while that can also use the configured transient retries and structural repairs. Null
ConfigKit's effective output and provenance contain no resolved secret values. does not disable validation. Numeric zero and false
retain their field meaning, subject to validation. Inspect recorded origins and
Current invocation syntax belongs in [CLI](cli.md). 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 ## 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 documented in the [release procedure](release.md#prerequisites). From the
repository root: repository root:

View File

@@ -1,26 +1,26 @@
# OpenAI-Compatible LLM Integration # 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, built-in OpenAI-compatible transport. PromptKit owns chat-completions wire framing,
provider envelope parsing, transient retries, per-generation timeouts, and JSON provider envelope parsing, transient retries, per-generation timeouts, and JSON
Schema repair. A backend's configured base endpoint must support the selected Schema repair. A backend's configured base endpoint must support the selected
profile's model and structured JSON-schema responses; local configuration profile's model and structured JSON-schema responses; local configuration
inspection does not contact the provider. inspection does not contact the provider.
Audita selects a role profile, supplies its registered backend credential, and Audita selects role profiles independently for each pipeline entry and supplies
passes the embedded response schema as a complete per-call output contract. It its domain response schema and per-operation budget. PromptKit owns backend and
prepares each call once, checks that the prepared target still matches the credential selection, request preparation, transport, retries, repairs, and
inspected backend and endpoint, then executes that same prepared request. A admission. Audita executes the same prepared handle and retains its own domain
profile cannot introduce a separate credential environment lookup. An absent validation. Profiles may use native endpoint and credential settings; local
backend credential permits an unauthenticated local service. inspection does not resolve a credential value or call the provider.
`llm.transient_retries` counts additional attempts for eligible transient `llm.transient_retries` counts additional attempts for eligible transient
failures; explicit zero makes one attempt. `llm.repair_attempts` counts failures; explicit zero makes one attempt. `llm.repair_attempts` counts
additional generations for schema-invalid model output. The operation timeout additional generations for schema-invalid model output. The operation timeout
covers preparation, capacity waiting, retries, generation, and repair. Caller covers preparation, capacity waiting, retries, generation, and repair. Caller
cancellation or an earlier deadline also applies. See [configuration](../config.md#settings) 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 defaults and the [PromptKit consumer contract](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.23.0/docs/consumers/pkg-promptkit.md)
for the pinned protocol and retry details. for protocol and retry details.
A model operation that exhausts structural repair, a live-parent local operation A model operation that exhausts structural repair, a live-parent local operation
timeout, capacity rejection, transport failure, malformed provider response, 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 internal failures remain fatal and cancel peers. Audita decodes into domain
types only after PromptKit validates the JSON. Ordinary reports use safe reason types only after PromptKit validates the JSON. Ordinary reports use safe reason
codes and counts rather than provider messages. Full request/response content 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` The corrected transcript uses the selected `output.schema`: `bare-segments`
or `audita-v1`. Its schema and text rules are unchanged by resilience or `audita-v1`. Its schema and text rules are unchanged by resilience
reporting. See [configuration](../config.md#settings) for selection and 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: With reporting enabled, Audita produces three ordinary files:
@@ -46,24 +46,34 @@ remain in opt-in debug files.
## Error and Recovery Records ## Error and Recovery Records
An `errors` record with `scope: work_unit` identifies zero-based `stage_index` 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 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 zero-based batch index, safe reason/message, sorted proposal indices when
known, and execution counts when available. Multiple failed batches in one known, and execution counts when available. Multiple failed batches in one
work unit form one error record. `scope: run` instead records phase, safe reason work unit form one error record. A record with scope `run` records a fatal
and message, optional origin, and output path where relevant. It can describe processing failure or a separate output delivery failure. It identifies the
a fatal error or secondary output-write failure without inventing a failed phase, safe reason and message, and available origin. A processing origin can
model work unit. Raw provider errors and transcript text are absent. 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 For `validation_decisions_invalid`, proposal indices identify only candidates
whose required decisions were unavailable. Other candidates in the same batch whose required decisions were unavailable. Other candidates in the same batch
may still be approved or rejected normally. 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 `reasons`, a safe message, available execution counts, and sorted
`filtered_proposals` details. One recovery can contain `output_repaired`, `filtered_proposals` details. One recovery can contain `output_repaired`,
`service_recovered`, and `proposals_filtered` together. Filtering covers `service_recovered`, `correction_revised`, and `proposals_filtered` together.
defective response proposals; low confidence, protected-term rejection, `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 ordinary editorial rejection, and an apply-time conflict caused by an earlier
accepted correction are not filtering recoveries. Failed operations are errors, accepted correction are not filtering recoveries. Failed operations are errors,
not recoveries. The initial chunk identity remains stable even if earlier 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 `report.md` includes run ID, status, corrections, work coverage, error and
recovery totals, input/output paths, and full work-unit error and recovery 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 matrices. Rows show every initial chunk with 1-based chunk number and initial
segment range; columns follow configured module-instance order, including segment range; columns follow configured pipeline order, including repeated modules. Labels show
repeats. Completed error cells are `0` or `1`; recovery cells are operation 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. 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 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 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 counts need not sum to the recovery total. When a repair was attempted, a
files. It does not include transcript excerpts or correction lists. 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 ## Debug-Only Files
With `--debug`, `correction-ledger.json` contains proposed candidates and With `--debug`, `correction-ledger.json` contains proposed candidates and
their application, rejection, or interruption details. `llm-execution.json` their application, rejection, or interruption details. `llm-execution.json`
holds logical calls and PromptKit execution events; `utilization-diagnostics.json` holds logical calls and PromptKit execution events. Interaction request/response
groups backend capacity and timing observations while preserving known and artifacts and input snapshots are also debug-only. Records carry zero-based
complete usage semantics. Interaction request/response artifacts, selected `stage_index` and optional `stage_id` where an entry is identified.
profiles, configuration provenance, and input snapshots are also debug-only.
These files are diagnostic evidence, not an alternate ordinary report schema. 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 Each candidate-backed ledger entry includes `proposed_corrected_text`, the
literal replacement span, even when it is `""` for a deletion. Applied entries literal replacement span, even when it is `""` for a deletion. Applied entries
also include `applied_corrected_text`, likewise `""` for an applied deletion. 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 ## Invocation
Use an argument array with the transcript path and required glossary argument, Use an argument array with the transcript path and configured glossary selections,
following the [process examples](../cli.md#commands-and-help). For machine workflows, following the [process examples](../cli.md#processing). For machine workflows,
select an explicit transcript file destination and a configuration path. Reports select an explicit transcript file destination and a configuration path. Reports
go beside the transcript unless an explicit `--report-dir` selects another go beside the transcript unless an explicit `--report-dir` selects another
directory. For stdout output, reports use the effective `reporting.stdout_dir` directory. For stdout output, reports use the effective `reporting.stdout_dir`
(defaulting to the invocation working directory), including a `--report-dir` (defaulting to the invocation working directory), including a `--report-dir`
override. A config-file or overlay value for `reporting.stdout_dir` alone does 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 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 Supplying a configuration path also makes file selection predictable; only
explicitly referenced credential variables are read from the environment. 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 Resolve the executable deliberately and set the child's working directory so
relative input/output paths and reported artifact paths have a known base. relative input/output paths and reported artifact paths have a known base.
Read stdout and stderr concurrently to avoid pipe blocking, and impose timeout 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 ## Result Handling
Interpret the exit result according to the 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 Consume transcript/report data through the
[output-file contract](output-files.md), and treat stderr as human-readable detail. [output-file contract](output-files.md), and treat stderr as human-readable detail.
The three reports may be absent after early configuration or destination Audita loads configuration and parses the input transcript before report
failures. After initialization, failed reports can describe invalid input or initialization. Early destination failures can also leave no reports. After
partial processing and use the same selected report directory as successful initialization, failed reports can describe partial processing or output
runs. Exit `0` can include recoverable model errors and applied 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 corrections; inspect `errors.yml` and `recoveries.yml` for those outcomes. A
transcript may have been written before a later required report failure, so transcript may have been written before a later required report failure, so
the file alone does not prove completion. the file alone does not prove completion.
If processing fails, preserve available evidence and follow 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 Ordinary reports are independent of optional retained debug evidence. Parent
cancellation reaches the child through its context; Audita joins workers and cancellation reaches the child through its context; Audita joins workers and
attempts failed-status report finalization before exiting. Uncatchable 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) - [Transcript and glossary inputs](transcript-glossary-files.md)
- [LLM endpoint compatibility](openai-compatible-llm.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 | | 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 | | `speaker` | Non-empty string |
| `start`, `end` | Numeric seconds, finite and non-negative; end must be at least start | | `start`, `end` | Numeric seconds, finite and non-negative; end must be at least start |
| `text` | Non-empty string | | `text` | Non-empty string |
@@ -21,30 +21,18 @@ schema/version marker.
Supply explicit start and end times for meaningful timing. The current decoder Supply explicit start and end times for meaningful timing. The current decoder
uses zero for missing or null timestamps rather than enforcing their presence. uses zero for missing or null timestamps rather than enforcing their presence.
String validation checks empty values, not whitespace trimming. Normalization can String validation checks for empty values. Normalization can merge segments and
merge segments and reassign IDs, so source IDs need not match output IDs. reassign IDs, so source IDs need not match output IDs.
The [tiny transcript](../../examples/tiny-transcript.json) is a complete copyable The [tiny transcript](../../examples/tiny-transcript.json) is a complete copyable
input. Invalid JSON, unsupported top-level shapes, empty transcripts, invalid field input. Invalid JSON, unsupported top-level shapes, empty transcripts, invalid field
types, duplicate supplied IDs, and the validation failures above are rejected. 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. Glossary definitions are composed as application configuration, including the
optional companion inputs described by the [configuration reference](../config.md).
| Entry field | Type and validation | The [local example](../../examples/local/glossary.yml) provides a complete
| --- | --- | collection. Configuration may contain empty collections; processing preflight
| `name` | Non-empty string | requires every glossary-correction entry to select at least one glossary entry.
| `category` | Non-empty string | The previous standalone `glossary` file format is not a processing input.
| `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.

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`. 1. Update fields, defaults, loading, and validation in `internal/core/config`.
2. Update file, selected overlay, credential reference, and CLI mapping as 2. Update file, selected overlay, credential reference, and CLI mapping as
applicable. Preserve the precedence defined in the 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. distinct validation and effective-config commands.
3. Update redaction when secrets are involved. 3. Review configuration tests and related CLI tests for precedence, validation,
4. Review configuration tests and related CLI tests for precedence, validation,
and source-specific behavior. Add or adjust tests for the changed contract and source-specific behavior. Add or adjust tests for the changed contract
according to the [testing policy](../policy/testing.md). 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 ## 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 The `version` route uses ReleaseKit's public `buildinfo.Version()` accessor and
stays independent of application runtime assembly. Preserve its behavior from 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). 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 ## Validating Examples
Keep complete copyable files in [examples](../../examples/) and link to them from Keep complete copyable files in [examples](../../examples/) and link to them from
their canonical contract documentation. Keep them valid and secret-free. their canonical contract documentation. Keep them valid and secret-free.
From the repository root, validate the maintained configuration examples: Run the commands in the [example guide](../../examples/README.md) from each
project's directory. `internal/cli/examples_integration_test.go` exercises the
```sh maintained projects with a controlled provider, and the preview fixture can be
go run ./cmd/audita config validate --config examples/minimal-config.yml prepared without inference. Review automatic companion sources and overlays in
go run ./cmd/audita config validate --config examples/configkit-inheritance.yml their actual project directories. Keep service credentials synthetic in tests.
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.
## Runtime Change Checks ## 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 - Process/output changes: verify stdout, stderr, exit, output-file, and report
behavior against the [CLI contract](../cli.md) and behavior against the [CLI contract](../cli.md) and
[subprocess guidance](../integrations/subprocess.md), including failures. [subprocess guidance](../integrations/subprocess.md), including failures.
- Report or diagnostics changes: review [report assembly tests and redaction - Report or diagnostics changes: review [report assembly tests](diagnostics-reporting.md#key-tests), metadata fields, and artifact paths.
checks](diagnostics-reporting.md#key-tests), metadata fields, and artifact paths.
- Schema or serialization changes: review [output-schema tests](output-schemas.md#key-tests) - Schema or serialization changes: review [output-schema tests](output-schemas.md#key-tests)
and `internal/core/schema` tests, including supported formats and rejection of and `internal/core/schema` tests, including supported formats and rejection of
unsupported schemas. 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 operation. Reports order stages, sections, validators, and batches by semantic
identity, never concurrent completion time. The core reporting package owns identity, never concurrent completion time. The core reporting package owns
Audita's versioned YAML DTOs, fixed Markdown rendering, and brief CLI Audita's versioned YAML DTOs, fixed Markdown rendering, and brief CLI
completion formatter. YAML redaction walks serialized string nodes so numeric completion formatter. Reports encode the typed documents directly to YAML. Ordinary reports omit raw causes,
and boolean values retain their types. Ordinary reports omit raw causes,
transcript text, complete decisions, and token/timing payloads. transcript text, complete decisions, and token/timing payloads.
Validation operations with unavailable decisions report only affected requested Validation operations with unavailable decisions report only affected requested
indices, even when other candidates in the batch continue. Ignored extra 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 operation; they do not count as filtered correction proposals. Failed operations
retain their execution counts and never produce a recovery record. retain their execution counts and never produce a recovery record.
`internal/core/diagnostics.OutputSession` owns active destination checks, `internal/core/diagnostics.OutputSession` owns destination selection, report
transcript preflight, report initialization, regular-file replacement, and direct initialization, and publication. Transcript and report files share a staging
stream publication. Transcript input is protected from early report writes but primitive that writes beside the resolved destination. Streams are opened for
may be the final transcript destination. The LLM runtime records successful reads delivery. Transcript input is protected from early report writes but
through PromptKit's profile filesystem and supplies those source paths to CLI; 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. no second filename-based discovery rule is used.
CLI composes it after configuration/profile inspection and before reading CLI composes it after configuration, transcript acquisition, and preflight
inputs or dispatching model work. It does not create ordinary report parents. readiness and before dispatching model work. It does not create ordinary report parents.
On a final write error it attempts other enabled reports and one failed-status Final report rendering includes delivery and cleanup errors observed so far.
pass; a published transcript is never erased by a later report failure. 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 Debug is independent. The shared `--debug` flag enables a unique retained child
under `diagnostics.work_dir`. CLI passes empty diagnostics paths and nil writers under `diagnostics.work_dir`. The CLI creates one interaction sink rooted in
when debug is off. With debug on, source/normalized snapshots, invocation, that directory and passes it to proposal generation, validation, and repair.
effective settings, origins, profiles, initial chunk summary, correction ledger, With debug enabled, it saves the source bytes as acquired, separate from the parsed and normalized
indexed execution/utilization, and model interactions are written. Runner transcript snapshots. It also captures invocation metadata, effective settings
candidate capture includes proposals later rejected or interrupted. Ledger rendered by ConfigKit, the correction ledger, LLM execution observations, and
mapping uses optional string pointers so an empty proposed replacement is model interactions. Candidate capture includes proposals later
serialized for every candidate and an empty applied replacement appears only rejected or interrupted. Repair and revalidation artifacts use section, proposal,
when that candidate applied; see the [public artifact contract](../integrations/output-files.md#debug-only-files). attempt, validator, and batch coordinates as applicable. Request metadata records
Debug write failures reach the CLI through an explicit concurrency-safe diagnostic these coordinates with the interaction role. Proposal request metadata carries
callback and produce redacted stderr messages without aborting processing. the zero-based response origin (`start_index`) and the ordered `segment_ids`
Completed validator decisions returned with a fatal batch error remain available used to interpret response references. Each interaction retains its available
to the debug ledger; they never authorize applying an incompletely validated edit. prepared request, response, and failure evidence. Ledger mapping preserves empty
Runner decision records carry the validator's explicit approved, rejected, or proposed and applied replacements and distinguishes unavailable candidates from
unavailable disposition into the ledger. Unavailable candidates have a distinct interrupted work.
top-level ledger disposition, while fatal interruptions remain interrupted when While final proposal indices are pending, repair request snapshots share their
no rejection or unavailable decision was returned. Successful validation unchanged message prefix. Each written request contains its full history.
interaction payloads contain the full decoded response, final content, and
reconciliation outcomes; ignored indices do not become ledger candidates. The sink groups concurrent write failures by role, artifact operation, and cause.
Every debug writer uses all configured backend secrets for redaction, including Warnings report the count and an affected path. The writer still attempts other
unselected backend credentials and source snapshots. Debug can still contain artifacts and returns the paths it wrote, and the CLI presents warnings separately
sensitive transcript and prompt content. 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 ## Key Tests
@@ -61,3 +74,17 @@ Useful tests: `internal/core/reporting/*_test.go`,
`internal/core/diagnostics/*_test.go`, `internal/core/diagnostics/*_test.go`,
`internal/framework/processreport/*_test.go`, and `internal/framework/processreport/*_test.go`, and
`cmd/audita/main_integration_test.go`. `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 # 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 Each resolved pipeline entry receives role-bound clients with its selected
catalogs and defaults are followed by Audita's embedded prompt and schema profiles and effective budgets. Clients share engine-local backend admission.
inputs, operator documents from `profiles_dir`, and the highest-priority The adapter uses ordinary `Run` with `OperationTimeout` and `OnPrepared`, passes
application backend mapping. Audita owns backend endpoints, capacity settings, Audita's per-call schema and repair budget, and decodes only validated results.
and resolved credentials; native PromptKit layering owns profile inheritance, The operation budget includes preparation, admission, retries, and structural
prompt overrides, and provider-specific fields. Imports are disabled. The repair. An expired parent context stops processing and retains any native cause.
runtime inspects both selected roles offline, requiring complete model and With an active parent, PromptKit's operation deadline remains recoverable even
endpoint values and rejecting competing profile credential lookups. A when a preparation error wraps it. A native transport timeout affects the HTTP
role-bound `llm.RoleClient` implements `structuredoutput.Client`; proposal and attempt and is recorded as a transport failure. The prepared notification
validator contracts alias that interface. Both roles share engine-local backend supplies prompt metadata to observers. With debug capture enabled, it also
capacity. 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 When correction repair is enabled, the runner checks the module's repair prompt
contents. The runtime does not reload operator documents or message files during and coordinator before submitting proposal work. The proposal call captures a
calls. If final engine construction fails, an embedded-only diagnostic native immutable PromptKit exchange. Each actionable correction starts an independent
construction distinguishes shipped asset failures from invalid operator input. `Engine.Coordinate` branch from that exchange. PromptKit assembles continuation
An asset failure remains an asset error; when embedded construction succeeds, history, owns the additional-turn budget, and delivers the last permitted response
the original failure remains a configuration error. The diagnostic engine for assessment. Follow-ups select the repair prompt, profile, and output schema
never replaces or executes the requested configuration, and caller cancellation directly; Audita does not rerender the original proposal or assemble replay messages.
skips this path. The captured inspection also supplies an internal source An opaque exchange in the structured-output contract keeps provider state outside
ledger: all loaded host YAML plus effective, source-relative host modules and validators. The adapter shares request construction, notifications,
`content_file` resources are tracked for output-collision checks. 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 Audita owns actionable rejection, revision decoding, withdrawal, current previews,
record before preparation. It supplies the reserved hardening text, the selected and full revalidation. Each branch returns its attempt facts and final approval
profile and resolved backend credential, and the complete embedded schema/repair to the section runner. Accepted siblings remain independent. Requesting more work
contract. `PrepareExecution` produces the exact messages and hashes retained in at the budget boundary produces exhaustion without allocating another logical call.
an Audita snapshot. The adapter checks the prepared backend and endpoint before A canceled, undelivered response supplies diagnostic evidence only; it cannot enter
`RunPrepared`. It records available final content, usage, model, and profile the approved set. Repair disabled in configuration bypasses coordination entirely.
metadata and decodes only a validated result. Call hooks expose logical The runner supplements each repair instruction with its current proposal preview
start/finish records and PromptKit execution events for debug utilization. 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 The observation collector tracks logical calls and execution events, and enrolls
wire ownership and failure behavior. `structuredoutput.Failure` has a safe selected runs in a native `ExecutionGroup`. Proposal, repair, and nested validator
message, fixed reason code, typed cause, and recoverable/fatal/canceled class. clients explicitly share the invocation observer; history reuse adds no extra run.
Counts distinguish provider attempts, transient retries, and structural Native summaries deduplicate terminal totals by run ID and retain terminal coverage
repairs, including on errors. Secrets from all configured backends, including unselected separately from usage presence and completeness. Logical calls and run membership
ones, are available to the diagnostics redaction boundary. can differ, especially on failures before execution.
CLI explain output and debug configuration origins share a value-free projection Processing operations retain the failure class, reason, and underlying error.
of effective field origins. The [CLI contract](../cli.md) defines its optional When a client omits the reason, the operation uses `internal_failure` and keeps
inheritance evidence fields. the original class and error chain. Ordinary reports use compact outcomes.
Request and response evidence is optional debug material. The runner preserves
## Orchestration ordered pipeline traversal and deterministic section collection while canceling
and joining peers on fatal errors.
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.

View File

@@ -13,7 +13,13 @@ Modules implement `contracts.TranscriptModule`:
- `Validators()` - `Validators()`
- `Propose(ctx, req)` - `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 ## Built-In Modules
@@ -37,13 +43,13 @@ Shared proposal-generation plumbing is centralized in:
Module packages own: Module packages own:
- prompt selection (`internal/prompts` prompt IDs). - prompt selection (`internal/prompts` prompt IDs).
`proposal_generation.BuildProposalVariables` encodes the glossary, selected Each stage prepares the encoded glossary context and protected spellings once.
transcript section, and trimmed description once for all four modules. PromptKit Proposal generation adds the selected transcript section and trimmed description
renders their embedded definitions from those variables and validates the for each request. PromptKit renders the selected definition and validates the
correction-set schema before Audita maps proposals. Domain validators still 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 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. segment IDs, preserving response order and multiple proposals per segment.
Unknown references become invalid-target candidates for the existing domain Unknown references become invalid-target candidates for the existing domain
checks; they are never interpreted as actual transcript IDs. Debug request 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 ## 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 Module construction failures are fatal. Recoverable proposal model failures
record an unsuccessful operation and yield no candidates for that section; record an unsuccessful operation and yield no candidates for that section;
other sections and module instances continue. Fatal adapter or application 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 ## 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>`. 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 2. Keep module prompt selection in the module and its definition in
`internal/prompts`; see [prompt assets](prompts.md). `internal/prompts`; see [prompt assets](prompts.md).
@@ -86,6 +108,6 @@ outcomes are defined by the [report contract](../integrations/output-files.md).
## Key Tests ## Key Tests
- `internal/modules/*/module_test.go` - `internal/modules/*/module_test.go`
- `internal/framework/modules/registry_test.go` - `internal/modules/registry_test.go`
- `internal/framework/proposal_generation/*_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 Configuration validation checks registry support. CLI orchestration resolves the
selected encoder, passes the final transcript to it, and routes the encoded bytes 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 An unsupported key fails validation or resolution rather than selecting an
implicit fallback. implicit fallback.
The registry delegates bare segment serialization to the transcript schema 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). receives the selected key separately; see [report assembly](diagnostics-reporting.md).
## Changing an Encoder ## Changing an Encoder

View File

@@ -14,6 +14,7 @@ Executable and command orchestration:
Core deterministic components: Core deterministic components:
- `internal/core/config` - `internal/core/config`
- `internal/core/glossary`
- `internal/core/schema` - `internal/core/schema`
- `internal/core/normalization` - `internal/core/normalization`
- `internal/core/chunking` - `internal/core/chunking`
@@ -24,7 +25,7 @@ Core deterministic components:
Framework orchestration and contracts: Framework orchestration and contracts:
- `internal/framework/contracts` - `internal/framework/contracts`
- `internal/framework/modules` - `internal/framework/preflight`
- `internal/framework/proposal_generation` - `internal/framework/proposal_generation`
- `internal/framework/proposals` - `internal/framework/proposals`
- `internal/framework/runner` - `internal/framework/runner`
@@ -37,6 +38,7 @@ Framework orchestration and contracts:
- `internal/framework/stagename` - `internal/framework/stagename`
Domain implementations: Domain implementations:
- `internal/modules` (built-in module composition)
- `internal/modules/*` - `internal/modules/*`
- `internal/validators/*` - `internal/validators/*`
- `internal/prompts` - `internal/prompts`
@@ -65,8 +67,8 @@ artifact lifecycle.
## Component Responsibilities ## Component Responsibilities
Core components implement configuration defaults/loading/validation/redaction, Core components implement configuration defaults, loading, and validation,
transcript and glossary schemas, normalization and chunking, output encoding, transcript schemas and derived glossary views, normalization and chunking, output encoding,
diagnostics artifact helpers, and public report structures. diagnostics artifact helpers, and public report structures.
Framework components implement module and validator contracts, proposal 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 formats; [configuration](../config.md) owns settings; the
[output contract](../integrations/output-files.md) owns serialized results. [output contract](../integrations/output-files.md) owns serialized results.
1. CLI filesystem adapters read transcript and glossary files. Schema parsing 1. CLI loads resolved configuration and transcript input. Preflight checks all
produces source objects; transcript segments enter canonical normalization. selected glossary views and roles before the output session prepares resources.
2. Normalization sorts and merges segments using configured time and token Transcript segments then enter canonical normalization.
limits, reassigning IDs where needed. 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 3. The runner partitions the normalized transcript exactly once before its
module loop. Initial section identity, segment membership, and token module loop. Initial section identity, segment membership, and token
estimates stay fixed while text evolves. estimates stay fixed while text evolves.
4. Module instances execute in configured order. Sections may propose 4. Module instances execute in configured order. Each section hands its decoded
concurrently, but proposal indices follow section order and response order. 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 5. Deterministic validators precede LLM-backed validators. Every submitted
candidate receives one decision per validator on a normal return. Fatal returns candidate receives one decision per validator on a normal return. Fatal returns
may preserve a checked subset of completed decisions as diagnostic evidence. may preserve a checked subset of completed decisions as diagnostic evidence.
Recoverable failed batches mark their candidates unavailable; successful Recoverable failed batches mark their candidates unavailable; successful
survivors continue through all required validators. 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 proposal-index order within their owning section. Existing replacement
policies and apply-time safety checks resolve stale conflicts. policies and apply-time safety checks resolve stale conflicts. Skip
7. CLI encodes the final transcript and publishes active files through the 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, output session. `framework/processreport` builds one snapshot for YAML,
Markdown, and CLI totals. Debug evidence is captured separately when enabled. 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 operation outcomes, and per-module results. Candidate payloads are retained
in the returned output only when debug capture is requested. A work unit can in the returned output only when debug capture is requested. A work unit can
complete with model errors and applied corrections. Recoverable model failures complete with model errors and applied corrections. Recoverable model failures
never trigger shared cancellation. Fatal setup, internal, application, or never trigger shared cancellation. Fatal failures and parent cancellation stop
parent-cancellation errors cancel peers, join workers, and preserve earlier further dispatch and join active workers. The initiating error carries its
committed module text for partial reports; no completed transcript is published. 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 Required transcript/report write failures are fatal. Optional debug writes
report safely to stderr without changing decisions or exit status. See report safely to stderr without changing decisions or exit status. See

View File

@@ -1,37 +1,54 @@
# Audita Prompt Registry # Audita Prompt Registry
`internal/prompts` embeds seven PromptKit YAML definitions under `internal/prompts` embeds eleven PromptKit definitions in the `audita`
`assets/prompts`. The IDs and selected version remain: 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`) PromptKit composes embedded defaults with operator prompt sources. Shared
- `modules.homophones.proposal` (`v1`) instructions come from the embedded fragments in `assets/shared`; the request
- `modules.spoken_word.proposal` (`v1`) shared-variable helper fills absent `HardeningPolicy`, `ProposalContract`,
- `modules.grammar.proposal` (`v1`) `RepairContract`, and `ValidationContract` variables. The processing adapter
- `validators.spoken_form_plausibility` (`v1`) supplies the embedded instruction fragments for those names. Processing supplies
- `validators.meaning_reversal_review` (`v1`) Audita's response-schema contract separately.
- `validators.editorial_review` (`v1`) 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 The correction-set schema requires a string replacement and accepts an empty
string. Proposal guidance uses it for eligible span deletion and permits literal string. Proposal guidance uses it for eligible span deletion and permits literal
spacing edits; validator guidance evaluates the full before/after segment under 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. rejection, not a structural schema error.
`internal/framework/responseschema` remains the only embedded source for `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 filesystem to PromptKit and retains Audita's schema-key lookup. PromptKit's
prepared execution supplies definition and rendered hashes; Audita does not prepared execution supplies definition and rendered hashes; Audita does not
recompute or promise equality with hashes from the removed template renderer. recompute or promise equality with hashes from the removed template renderer.
The small Audita registry records only prompt ID, version, source, and embedded The small Audita registry records only prompt ID, source, and embedded path. Prepared runtime metadata belongs in diagnostics rather than the registry.
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 response-schema key, and logical-call attribution. Module and validator callers
pass these values through the role-bound adapter. See the pass these values through the role-bound adapter. See the
[LLM runtime](llm-runtime.md) for runtime assembly and [LLM runtime](llm-runtime.md) for runtime assembly and
[configuration](../config.md) for operator-selected profiles. [configuration](../config.md) for operator-selected profiles.
Proposal instructions describe literal matching, each module's replacement policy, 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 Proposal `id` and validator `correction_index` values are short, one-based
references scoped to each request, not internal transcript/proposal identities. references scoped to each request, not internal transcript/proposal identities.
Mapping belongs to [proposal generation](modules.md) and Mapping belongs to [proposal generation](modules.md) and
[validator reconciliation](validators.md). Validator instructions distinguish [validator reconciliation](validators.md). Validator decisions use `approved` for the verdict. Approval examples use an empty
confidence in the verdict from the verdict itself. Compact output examples `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 illustrate the supplied schema without requiring fixed JSON formatting or key
order. The grammar article exception and glossary mishearing exception apply order. The grammar article exception and glossary mishearing exception apply
consistently across their instructions. consistently across their instructions.
@@ -66,3 +89,35 @@ consistently across their instructions.
Only the three active validator definitions are retained. The unused internal Only the three active validator definitions are retained. The unused internal
`grammar_review` and `spoken_word_review` definitions and type selections were `grammar_review` and `spoken_word_review` definitions and type selections were
removed; built-in chains and operator configuration are unchanged. 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: Deterministic:
- `proposal_shape` - `proposal_shape`
- `confidence_threshold`
- `original_text_presence` - `original_text_presence`
- `non_empty_resulting_segment` — rejects edits that would leave the segment - `non_empty_resulting_segment` — rejects edits that would leave the segment
blank, regardless of replacement-span length. blank, regardless of replacement-span length.
@@ -46,9 +45,25 @@ For each module section:
3. record decisions and compact operation outcomes; 3. record decisions and compact operation outcomes;
4. carry only approved proposals forward. 4. carry only approved proposals forward.
Decision cardinality is enforced inside Audita: each candidate proposal must When correction repair is enabled, the runner also gathers independent findings
receive exactly one outcome per validator it reaches. The runner still rejects for rejected candidates when a validator has usable evidence. Unavailable
duplicate, missing, or unknown identities in an internal validator result. 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 ## 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 map back to internal proposal identities; results are ordered by request identity
and satisfy strict internal cardinality before the runner advances and satisfy strict internal cardinality before the runner advances
approved candidates. An unavailable candidate never advances as approved. approved candidates. An unavailable candidate never advances as approved.
Invalid confidence in a decoded test double also makes only its candidate A partially unavailable batch records one failed
unavailable; production schema validation still rejects out-of-range confidence
before reconciliation. A partially unavailable batch records one failed
operation with only those requested indices, while a successful batch with operation with only those requested indices, while a successful batch with
ignored extras records a decision-filtering recovery. Fatal errors stop the ignored extras records a decision-filtering recovery. Fatal errors stop the
chain without returning unchecked candidates as approved. A local result builder 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). [deferred](../roadmap/future.md#domain-aware-response-recovery).
Debug request metadata records `proposal_indices` in local-reference order Debug request metadata records `proposal_indices` in local-reference order
(reference 1 is the first entry). Raw decoded responses and ignored indices use (reference 1 is the first entry). Decoding preserves the supplied numeric
local references; reconciled decisions and unavailable indices use internal 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 proposal indices. Batch token estimates use the same locally numbered payload
as prompt encoding. as prompt encoding.
@@ -116,19 +132,23 @@ is covered by [report assembly](diagnostics-reporting.md).
- `internal/validators/*_test.go` - `internal/validators/*_test.go`
- `internal/framework/validators/*_test.go` - `internal/framework/validators/*_test.go`
- `internal/framework/processreport/correction_ledger_test.go` - `internal/framework/processreport/correction_ledger_test.go`
- `internal/cli/run_test.go` - `internal/cli/process_ordered_integration_test.go`
## Supplemental Validation Context ## Supplemental Validation Context
Request construction prepares one segment-position lookup and protected vocabulary Each stage prepares a context matcher and indexes its selected glossary entries
for all candidates. Glossary selection remains candidate-specific, including the by identity. Request construction uses a segment-position lookup and returns
proposed replacement text. 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 Each candidate carries its target segment's supplied `speaker`, including an
available within its fixed chunk, labeled `preceding` or `following` with speaker, 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 text, and categories, plus glossary entries whose names, aliases, or
recognized plurals appear in its original/resulting text or those neighbors. 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. Model-facing candidate and neighboring context omit internal segment IDs.
This supplies evidence such as a troupe definition for a proposed `Jesters` This supplies evidence such as a troupe definition for a proposed `Jesters`
correction or an adjacent speaker turn explaining deliberate repetition. A correction 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. out-of-chunk context, or complete transcript is implied.
Context is serialized inside the validation item and included in the existing Context is serialized inside the validation item and included in the existing
payload token estimate. If one enriched item exceeds the configured limit, optional payload token estimate, including the target speaker. Fitting measures the
neighbors are removed from the end first, then glossary entries from the end, required data first, then considers glossary entries followed by neighboring
until it fits or only required candidate data remains. Required before/after text segments in order. It stops at the first entry that exceeds the budget. Required
is never truncated. Existing oversized-candidate handling still applies if that before/after text is never truncated. A candidate whose required data exceeds
required data does not fit. Context is supplemental, not a promise that every the budget receives an unavailable decision. The built-in estimator reuses
relevant definition or neighboring utterance always fits. This uses the existing encoded fragment counts for fitting and batching.
payload estimator, not a new guarantee about the provider's full context window.
## 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 Spoken-word cleanup may reduce repeated protected-name occurrences when every
original protected identity still appears in the resulting segment and surviving 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 exception only relaxes the deterministic count guard; editorial and meaning-reversal
validation still decide whether the repetition was accidental and the edit preserves validation still decide whether the repetition was accidental and the edit preserves
meaning. Intentional emphasis and substantive references remain protected by those 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 # 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. Audita v2 adopts ConfigKit for configuration and PromptKit for LLM execution.
Version-1 configuration files, environment overlays, and retired flags are not Version-1 configuration files, environment overlays, and retired flags are not
accepted. Copy a maintained [local](../../examples/minimal-config.yml) or accepted. Copy a maintained [local](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.1.1/examples/minimal-config.yml) or
[service](../../examples/production-config.yml) example, then select real models [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 in the accompanying `examples/profiles/` files. A testing overlay is shown at
`examples/overlays/testing.yml`; its model choice carries no cost, speed, or `examples/overlays/testing.yml`; its model choice carries no cost, speed, or
quality guarantee. 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 capacity and usage fields retain known/complete flags. Debug runs write
`effective-config.redacted.yaml`, `selected-profiles.yaml`, `effective-config.redacted.yaml`, `selected-profiles.yaml`,
`config-origins.yaml`, `utilization-diagnostics.json`, and `config-origins.yaml`, `utilization-diagnostics.json`, and
`llm-execution.json`. Request and response artifacts remain redacted debugging `llm-execution.json`. Request and response artifacts are debugging material. See [operations](../operations.md#debug-evidence) for placement
material. See [operations](../operations.md#diagnostics-directory) for placement
and paths, [configuration](../config.md) for all settings, and the and paths, [configuration](../config.md) for all settings, and the
[CLI reference](../cli.md) for current flags. [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 # Audita Operations
This guide owns physical output placement and failure handling. The This guide owns output placement and failure handling. The [CLI reference](cli.md)
[CLI reference](cli.md) owns flags and streams, [configuration](config.md) owns owns invocation, [configuration](config.md) owns settings, and the
settings, and the [output contract](integrations/output-files.md) owns schemas. [output contract](integrations/output-files.md) owns serialized formats.
## Normal Workflow ## Processing
1. Validate a version-2 configuration and its selected profiles with Inspect the application and PromptKit resources, prepare a transcript, then run
`audita config validate --config config.yml`. `audita process` with the desired destination. The [examples](../examples/README.md)
2. Prepare a transcript and glossary following the [input contract](integrations/transcript-glossary-files.md). show complete projects. Processing preflight checks every configured glossary
3. Run `audita process input.json --config config.yml --glossary glossary.yaml --output corrected.json`. correction and selected profile before output preparation and model work. Empty
4. Check the exit status, stderr summary, corrected transcript, and reports. protection and an empty pipeline are valid. A completed run can contain
A completed run can contain recoverable model errors and still apply recoverable model errors while still applying independently validated edits.
corrections that passed every required validator. 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`, Treat the selected main file, imports, overlay, and automatically loaded
`recoveries.yml`, and `report.md` go in the transcript output's parent directory glossary and prompt companions as one trusted bundle. Choose the working
unless `--report-dir` is explicitly supplied. For stdout transcript output, they directory deliberately when using automatic discovery. A bundle can select
go in the effective `reporting.stdout_dir` (default `.`), including a the provider, prompt content, and local files consumed by processing. Review
`--report-dir` override. A config-file or overlay value for these sources before running with sensitive transcript data. Native inspection
`reporting.stdout_dir` alone does not redirect file-output reports. An active describes the loaded configuration and resources. Processing readiness also
selected report directory must be nonblank. `--reporting=false` suppresses all depends on the profiles and glossaries selected by the pipeline. See
three reports and leaves their destination inactive, so it is not probed merely [configuration loading](config.md#loading-and-composition) for discovery rules.
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.
Existing report directories and parents for regular transcript files must be ## Outputs and lifecycle
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.
With reporting enabled, all three reports are initialized as `in_progress` before Reporting is enabled by default. For transcript file output, `errors.yml`,
input processing. Output is encoded fully before publication. Each regular output `recoveries.yml`, and `report.md` are placed beside that file unless `--report-dir`
file is replaced through a temporary file on its destination filesystem: is supplied. For stdout transcript output they use the effective report directory.
transcript first, then `errors.yml`, Disabling reporting leaves its destination inactive and unprobed. Quiet mode
`recoveries.yml`, and `report.md`. This is per-file replacement, not a requires a transcript file or `/dev/null`; it suppresses optional messages, not
multi-file transaction. New files honor the process umask; replacing an existing failures. Stdout carries transcript JSON when selected.
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`.
## 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 Enabled reports are initialized as `in_progress` before processing. The
reporting. One directory named `run-<id>` is created under transcript is published before final reports; the files do not form a single
`diagnostics.work_dir` (default `/tmp/audita`), which `--work-dir` can override, transaction. A late report failure may therefore leave a published transcript.
and retained on success or failure. Selecting `--work-dir` alone does not enable After a required write failure or cancellation, Audita attempts to clean
capture. Without debug, no directory or payload files are created. The parent unpublished temporary resources and publish failed-status reports. A cleanup
is created when needed only for debug. Failure to failure is reported with the earlier error. Cancellation observed after a
write optional debug evidence prints a redacted stderr diagnostic but does not stream write still fails the invocation, even when some or all bytes reached
change correction decisions or the exit status. 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 ## Live progress
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.
## 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 ## Debug evidence
`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.
Read stderr and report status first. If a required output failed after a The shared `--debug` flag enables retained artifacts in a run directory beneath
transcript was published, do not treat the file alone as proof of a completed `diagnostics.work_dir`; selecting a work directory alone does not enable capture.
run. Fix the input, service, or destination problem and rerun. Audita has no Optional debug preparation or writes can produce warnings without
resume/checkpoint API. 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 Material: All documents under `docs/policy/`, root `AGENTS.md`, and the Policy
Reading Guide in `docs/development.md`, adapted for this repository. Reading Guide in `docs/development.md`, adapted for this repository.
`docs/policy/release.md` incorporates revision `docs/policy/documentation.md`, `docs/policy/oss.md`, and `docs/policy/release.md`
`e833faddf120c789a9b45348edaf75720de16348`; the remaining listed material incorporate revision `593c9b52273c5c879785ae9e995d21026df467b4`.
incorporates revision `d84a38ebab26f048cafbe59a2246700c35d29843`. The remaining listed material incorporates revision
`d84a38ebab26f048cafbe59a2246700c35d29843`.
Copyright (C) 2026 Eric Rakestraw 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) | 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) | [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) | [LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) |
[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) | [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE). [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/d84a38ebab26f048cafbe59a2246700c35d29843).
[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348). [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4).
## ConfigKit ## 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 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) | License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3](licenses/GPL-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 ## 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 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) | License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3](licenses/GPL-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 ## 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. Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) | License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) |
[LICENSE](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/LICENSE) | [LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/PATENTS). [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 ## 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. Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) | 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) | [LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/crypto/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/crypto/PATENTS). [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 ## 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. Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) | 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) | [LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/net/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/net/PATENTS). [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 ## 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. Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) | 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) | [LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/sys/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/sys/PATENTS). [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 ## 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. Copyright 2009 The Go Authors.
SPDX-License-Identifier: BSD-3-Clause SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-Go.txt) | 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) | [LICENSE](https://github.com/golang/go/blob/7b2881024c95a11ddb86663a616340aa3a88b67f/src/vendor/golang.org/x/text/LICENSE) |
[PATENTS](https://github.com/golang/go/blob/c293dd49cbe25e1fe8d97d94a5cb618e7b6d831e/src/vendor/golang.org/x/text/PATENTS). [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 ## 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 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) | License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[MIT](licenses/MIT-libyaml-v4.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 ## 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 SPDX-License-Identifier: BSD-3-Clause
License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-x-text.txt) | License and notices: [BSD 3-Clause](licenses/BSD-3-Clause-x-text.txt) |
[LICENSE](https://github.com/golang/text/blob/6c97a165dd661335ff7bce6104a008558123c353/LICENSE) | [LICENSE](https://github.com/golang/text/blob/6070ac32abcdd1670599eeb3ee4d513c8184a513/LICENSE) |
[PATENTS](https://github.com/golang/text/blob/6c97a165dd661335ff7bce6104a008558123c353/PATENTS). [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 ## 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 SPDX-License-Identifier: Apache-2.0
License and notices: [Apache 2.0](licenses/Apache-2.0.txt). 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 ## 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 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) | License and notices: [LGPL v3](licenses/LGPL-3.0.txt) |
[GPL v3](licenses/GPL-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 SPDX-License-Identifier: Apache-2.0
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
License and notices: [Apache 2.0](licenses/Apache-2.0.txt) | License and notices: [Apache 2.0](licenses/Apache-2.0.txt) |
[MIT](licenses/MIT-libyaml.txt) | [LICENSE](https://github.com/spf13/cobra/blob/88b30ab89da2d0d0abb153818746c5a2d30eccec/LICENSE.txt).
[LICENSE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/LICENSE) |
[NOTICE](https://github.com/go-yaml/yaml/blob/f6f7691b1fdeb513f56608cd2c32c51f8194bf51/NOTICE).
[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 Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are 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 copyright notice, this list of conditions and the following disclaimer
in the documentation and/or other materials provided with the in the documentation and/or other materials provided with the
distribution. 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 contributors may be used to endorse or promote products derived from
this software without specific prior written permission. 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 **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) **Upstream Source:** [Standard Repository Policies architecture](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
## Purpose And Ownership ## Purpose And Ownership
@@ -72,13 +72,19 @@ hidden global state.
## Correction and Concurrency Invariants ## 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 - Treat LLM responses as nondeterministic inputs. Preserve deterministic proposal
indexing, validator ordering, transcript mutation, reports, and serialization. indexing, validator ordering, transcript mutation, reports, and serialization.
- Validate corrections before final mutation, including local proposal checks, - Validate corrections before final mutation, including local proposal checks,
decision cardinality, and apply-time safety. Provider-side schema enforcement decision cardinality, and apply-time safety. Provider-side schema enforcement
does not replace these checks. does not replace these checks.
- Keep LLM concurrency bounded and context-aware through PromptKit's engine-local - Use PromptKit's context-aware, engine-local per-backend admission for
per-backend admission. Proposal and validation calls selecting the same backend LLM concurrency. Proposal and validation calls selecting the same backend
share that capacity, including retries and repairs. Preserve deterministic share that capacity, including retries and repairs. Preserve deterministic
collection order. Recoverable model-operation failures stay local to their collection order. Recoverable model-operation failures stay local to their
proposal response or validation batch; fatal invariant/application failure 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 [CLI contract](../cli.md) and the artifact handling defined by
[operations](../operations.md). [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 ## Dependencies
Keep Audita dependency-light and prefer the Go standard library for CLI parsing, Keep Audita dependency-light and prefer the Go standard library where no adopted
filesystems, synchronization, and tests. ConfigKit owns configuration loading, library owns the boundary. ConfigKit owns configuration composition, presence,
presence, provenance, and secret resolution; PromptKit owns prompt/profile recorded resolution, and provenance. PromptKit owns prompt, profile, backend,
loading, OpenAI-compatible transport, retries, repairs, and backend admission. credential, transport, retry, repair, and admission behavior. CommandKit and its
Audita owns domain meaning, role selection, and deterministic processing. 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. frameworks without a concrete implemented need and focused tests.
## Testing and Documentation ## Testing and Documentation

View File

@@ -1,9 +1,9 @@
# Documentation Policy # Documentation Policy
**Base Policy Version:** 1.11 **Base Policy Version:** 1.12
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-11
**Upstream Source:** [Standard Repository Policies documentation](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md) **Upstream Source:** [Standard Repository Policies documentation](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/documentation.md)
## Purpose ## 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. | | 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. | | 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. | | 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. | | 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, deferred, or rejected work; implementation status, sequencing, and task breakdowns. | Implemented behavior reference and architectural decision rationale. | | 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. | | 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. | | 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 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. 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 ## Maintenance

View File

@@ -1,9 +1,9 @@
# Open Source Licensing And Attribution Policy # Open Source Licensing And Attribution Policy
**Base Policy Version:** 1.8 **Base Policy Version:** 1.9
**Last Updated**: 2026-09-28 **Last Updated**: 2026-11-11
**Upstream Source:** [Standard Repository Policies oss](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/oss.md) **Upstream Source:** [Standard Repository Policies oss](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/oss.md)
## Purpose And Scope ## 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 follow the author's selected scope rather than inferring different licenses for
individual packages. individual packages.
Use the upstream [application COPYRIGHT example](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/application/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/d84a38ebab26f048cafbe59a2246700c35d29843/examples/licensing/library/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. 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. Use verified project names, contribution years, and copyright holders.
For another selected license, adapt the grant, SPDX expression, disclaimer, and For another selected license, adapt the grant, SPDX expression, disclaimer, and
text references together to reflect the author's selected grant. 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`. filenames, such as `COPYRIGHT`, `LICENSE`, `NOTICE`, or `PATENTS`.
5. **Source repository link**, rendered exactly as `[Source](COMMIT_URL).`. 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`. to create the project’s `docs/oss/attribution.md`.
The example illustrates omitted fields and multiple copyrights and licenses. The example illustrates omitted fields and multiple copyrights and licenses.
Replace the uppercase placeholders and illustrative URLs with actual component Replace the uppercase placeholders and illustrative URLs with actual component

View File

@@ -1,9 +1,9 @@
# Release Policy # Release Policy
**Base Policy Version:** 1.6 **Base Policy Version:** 1.7
**Last Updated**: 2026-10-08 **Last Updated**: 2026-11-11
**Upstream Source:** [Standard Repository Policies release](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md) **Upstream Source:** [Standard Repository Policies release](https://gitea.maximumdirect.net/eric/policy/src/commit/593c9b52273c5c879785ae9e995d21026df467b4/docs/policy/release.md)
## Purpose ## Purpose
@@ -82,6 +82,14 @@ For releases at or after `v1.0.0`:
minimum as described below; and minimum as described below; and
- a patch release may make backward-compatible fixes. - 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, Before `v1.0.0`, a minor release may change a documented public, operational,
configuration, data, integration, or compatibility contract when the release configuration, data, integration, or compatibility contract when the release
note explains the impact and required consumer action. A patch release must 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. concrete risk and why ordinary change review or automation is insufficient.
Do not add routine confirmations for checks the command can perform itself. 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 ## Publication Guards
Automate the checks needed to publish the intended source under a fresh version: 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 ## Prerequisites
Use Bash and Git. The authoritative remote is `origin`, Use Bash, Git, a C compiler, and cgo for race detection. The authoritative
which must point to `https://gitea.maximumdirect.net/eric/audita.git`; the 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. primary branch is `main`. Source publication needs no delivery credential.
Woodpecker uses the existing `GITEA_RELEASE_TOKEN` secret for delivery. 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). The source-build minimum is Go 1.27.0, declared in [go.mod](../go.mod).
This minimum is required by the selected ReleaseKit dependency. This minimum is required by the selected application dependencies.
Distributed executables do not require a Go installation. The selected release 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 runtime notices. Use that local installation for tool bootstrap, candidate
validation, and release builds. Replace the installation path below with its validation, and release builds. Replace the installation path below with its
actual directory: actual directory:
```sh ```sh
export PATH="/path/to/go1.26.8/bin:$PATH" export PATH="/path/to/go1.27.4/bin:$PATH"
export GOTOOLCHAIN=local export GOTOOLCHAIN=local
go version 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 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; 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 `go mod tidy` retains its dependencies and checksums. The release wrapper changes
to the repository root and invokes `go tool releasekit` with workspace discovery to the repository root, selects the host target, and invokes the full
and automatic toolchain downloads disabled. Go builds or reuses the selected `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 tool from its normal build cache. Tool preparation precedes offline candidate
validation. 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. `COPYRIGHT | LICENSE | ATTRIBUTION` footer with links for the selected version.
Update affected canonical documentation with behavior changes. 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>`: End each note with this footer, substituting its complete tag for `<version>`:
```markdown ```markdown
@@ -78,9 +97,11 @@ Publish from the repository root, substituting the selected version:
bash scripts/release.sh publish VERSION bash scripts/release.sh publish VERSION
``` ```
The command runs `go test -mod=readonly -count=1 ./...` once with module and The command runs the offline Go test suite with race detection, full Go vet,
toolchain network access disabled, builds the profile's Linux amd64 and arm64 formatting, Markdown link, and module distribution checks. Race detection covers
targets, and checks the native version output. It creates an annotated tag whose 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 message comes from the committed note, then pushes the exact tag object. A
successful publication completes the source release without waiting for CI or successful publication completes the source release without waiting for CI or
checking artifact availability. checking artifact availability.
@@ -104,11 +125,13 @@ Woodpecker runs ReleaseKit's `ci-deliver` command for tags under
- `SHA256SUMS` - `SHA256SUMS`
Before running Go, the workflow fetches and verifies the event tag, checks it 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 `go.mod` and `go.sum` into temporary module metadata outside the checkout. Go
confirms that this configuration selects ReleaseKit, then builds its CLI using confirms that this configuration selects ReleaseKit, then invokes its CLI
an alternate `-modfile`. The bootstrap executable and temporary files remain using an alternate `-modfile` and the host target. Temporary metadata remains
outside the tagged source. The workflow runs with the selected Go 1.26.8 image, outside the tagged source. The workflow runs with the selected Go 1.27.4 image,
`GOWORK=off`, and `GOTOOLCHAIN=local`. `GOWORK=off`, and `GOTOOLCHAIN=local`.
Delivery uses prepared-checkout mode to verify the existing tag, HEAD, and clean 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: The resulting executable receives:
```sh ```sh
"$${bootstrap_dir}/releasekit" ci-deliver \ go tool -modfile="$${bootstrap_dir}/releasekit.mod" "$${releasekit_module}/cmd/releasekit" ci-deliver \
--repo "$${CI_WORKSPACE}" \ --repo "$${CI_WORKSPACE}" \
--prepared \ --prepared \
--commit "$${CI_COMMIT_SHA}" \ --commit "$${expected_commit}" \
"$${CI_COMMIT_TAG}" "$${CI_COMMIT_TAG}"
``` ```
@@ -131,8 +154,8 @@ after source publication; its status and logs report delivery progress or
failure. failure.
ReleaseKit handles content-aware retries and retained-artifact recovery. See 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) 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://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.1/docs/consumers/delivery.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 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 release. Retry the same immutable tag after resolving the reported state; do not
replace published files or a checksum manifest. 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 against that endpoint before retrying. An exact remote tag-object match, with
its source available on remote `main`, can confirm publication. If the remote 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 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. for object-level recovery details.
A source-release success and artifact-delivery status are separate. For a A source-release success and artifact-delivery status are separate. For a
partial or uncertain delivery, inspect the job output and follow the pinned 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; A source or published-content correction requires a new appropriate version;
leave the original tag and its contents intact. leave the original tag and its contents intact.

View File

@@ -1,5 +1,7 @@
# Release Notes # 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.1.0](v3.1.0.md)
- [Audita v3.0.1](v3.0.1.md) - [Audita v3.0.1](v3.0.1.md)
- [Audita v3.0.0](v3.0.0.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 3. Select a configuration root whose final definitions are valid. PromptKit now
validates unused definitions too, including backend references, and conflicting validates unused definitions too, including backend references, and conflicting
values within a directory source group are errors. The maintained examples values within a directory source group are errors. The maintained examples
use separate [local](../../examples/profiles/local/) and use separate [local](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/examples/profiles/local/) and
[service](../../examples/profiles/service/) roots. Runtime source edits take [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. effect on the next invocation.
4. Rename any application backend literally named `extends` and update its 4. Rename any application backend literally named `extends` and update its
profile references. ConfigKit now reserves that key for inheritance. 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 `audita config validate --config /path/to/config.yml`, including any selected
testing overlay. Application configuration continues to use `version: 2`. testing overlay. Application configuration continues to use `version: 2`.
The [configuration reference](../config.md#promptkit-profiles-and-operator-prompts) 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 maintained contains the migrated format and presence rules. Start from the
[local](../../examples/minimal-config.yml), [local](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/examples/minimal-config.yml),
[service](../../examples/production-config.yml), or [service](https://gitea.maximumdirect.net/eric/audita/src/tag/v3.0.0/examples/production-config.yml), or
[application inheritance](../../examples/configkit-inheritance.yml) examples. [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 The [CLI reference](../cli.md) describes report selection, and the
[release procedure](../release.md) describes source publication and asynchronous [release procedure](../release.md) describes source publication and asynchronous
Linux binary delivery. 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 # Deferred Feature Work
**Last updated:** 2026-10-11 **Last updated:** 2026-11-15
**Status:** Deferred or exploratory work; not implemented or scheduled. These **Status:** Deferred or exploratory work; not implemented or scheduled. These
entries preserve work beyond completed feature and library upgrades. entries preserve work beyond completed feature and library upgrades.
@@ -10,10 +10,11 @@ implementing every capability.
## Domain-Aware Response Recovery ## Domain-Aware Response Recovery
The implemented [partial-success decision reconciliation](../internal/validators.md#llm-validator-batching) The implemented [partial-success decision reconciliation](../internal/validators.md#llm-validator-batching)
preserves usable decisions without another model call. Guided recovery remains preserves usable decisions without another model call. Revision of rejected
deferred pending evidence from failures that remain. General per-entry correction proposals is implemented with substantive
salvage from structurally invalid responses is also a separate design question; validator feedback and explicit proposal withdrawal; see the
the accepted reconciliation feature retains whole-response structural validation. [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 Consider bounded feedback and regeneration for model responses that satisfy the
structural schema but leave requested decisions unavailable after reconciliation. 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 shared library capabilities where appropriate; do not introduce an uncoordinated
outer retry loop that multiplies existing retry/repair budgets. outer retry loop that multiplies existing retry/repair budgets.
Ordinary editorial rejection is a valid decision, not a reason to regenerate until Editorial rejection remains a valid decision about the evaluated proposal. The
an edit is approved. Recovery must preserve required validation, candidate identity, implemented correction repair loop handles subsequent revision and full
partial-success safety, and truthful error/recovery reporting. Validate with revalidation; this deferred entry concerns unavailable decisions. Decision recovery
controlled responses that distinguish recoverable protocol defects from valid must preserve required validation, candidate identity, partial-success safety,
negative decisions. Exact APIs, budgets, and sequencing remain undecided. 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 ## 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 consumers. Do not infer authorization to remove a segment from an empty string
or introduce segment-removal machinery as part of span-deletion consistency. 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 Consider an opt-in transcript corpus and live-model comparisons to assess needed
also provides prompt/profile listings and contextual prompt requirement and unnecessary edits, missed corrections, validator disagreement, and repair
inspection. Exposing these capabilities in Audita is deferred until a concrete outcomes through independent editorial review. Native PromptKit execution
operator or development need arises. The dependency upgrade did not select new summaries can supply request and usage measurements. Keep live calls outside
inspection commands. the offline test suite.
If a need emerges, define command ownership, selection syntax, report scope, and Broader validator context and combined semantic validation remain exploratory.
disclosure before implementation. Reuse the libraries' public APIs and consider A proposal to expand context should identify a captured case and the evidence
shared CLI conventions alongside any separately selected CommandKit adoption. missing from the validator request.
Requirement discovery is advisory evidence rather than proof of execution See the [current validator context](../internal/validators.md#supplemental-validation-context).
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).

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 ( require (
gitea.maximumdirect.net/eric/ConfigKit v0.7.1 github.com/santhosh-tekuri/jsonschema/v6 v6.0.3
gitea.maximumdirect.net/eric/ReleaseKit v0.4.1 go.maximumdirect.net/ckconfig v0.9.0
gitea.maximumdirect.net/eric/promptkit v0.14.0 go.maximumdirect.net/ckprompt v0.10.0
golang.org/x/mod v0.40.0 go.maximumdirect.net/commandkit v0.7.0
gopkg.in/yaml.v3 v3.0.1 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 ( require (
gitea.maximumdirect.net/eric/promptkit-backend-openrouter/v3 v3.20260930.0 // indirect github.com/inconshreveable/mousetrap v1.1.0 // indirect
gitea.maximumdirect.net/eric/promptkit-backend-rakestrawhome/v3 v3.20260930.0 // indirect github.com/spf13/cobra v1.10.2 // indirect
github.com/kr/pretty v0.3.1 // indirect github.com/spf13/pflag v1.1.0 // indirect
github.com/rogpeppe/go-internal v1.14.1 // indirect github.com/yuin/goldmark/v2 v2.1.16 // indirect
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 // indirect golang.org/x/mod v0.43.0 // indirect
github.com/yuin/goldmark/v2 v2.1.6 // indirect golang.org/x/text v0.44.0 // 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
) )
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= github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
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/dlclark/regexp2 v1.11.0 h1:G/nrcoOa7ZXlpoa/91N3X7mM3r8eIlMBBJZvsz/mxKI= 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/dlclark/regexp2 v1.11.0/go.mod h1:DHkYz0B9wPfa6wondMfaivmHpzrQ3v9q8cnmRbL6yW8=
github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk= github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ= github.com/santhosh-tekuri/jsonschema/v6 v6.0.3 h1:1EYB5IzjZawrrnELUi78f9fPu57HuXjmddZPjrls/28=
github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI= github.com/santhosh-tekuri/jsonschema/v6 v6.0.3/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU=
github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA= github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/rogpeppe/go-internal v1.9.0/go.mod h1:WtVeX8xhTBvf0smdhujwtBcq4Qrzq/fJaraNFVN+nFs= github.com/spf13/pflag v1.1.0 h1:6W6MbVUrnMb8PEhjkqwsVLY7ryuzRfFHF4mQd7L94ag=
github.com/rogpeppe/go-internal v1.14.1 h1:UQB4HGPB6osV0SQTLymcB4TgvyWu6ZyliaW0tI/otEQ= github.com/spf13/pflag v1.1.0/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7so1lCWt35ZSgc= github.com/yuin/goldmark/v2 v2.1.16 h1:MXvCVo+Cb2SVJ5cwJUzXetDjI7HECRJCkcqylEQtcJo=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2 h1:KRzFb2m7YtdldCEkzs6KqmJw4nqEVZGK7IN2kJkjTuQ= github.com/yuin/goldmark/v2 v2.1.16/go.mod h1:G6M4/qOFtfn01/o14BU1UR2Lo5N3S9Qo7xCuz/sHjGQ=
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2/go.mod h1:JXeL+ps8p7/KNMjDQk3TCwPpBy0wYklyWTfbkIzdIFU= go.maximumdirect.net/ckconfig v0.9.0 h1:s9Ikga4wt4K1NpLCX9bLhm5vbcm1Fgqy9yk2lmO4Sss=
github.com/yuin/goldmark/v2 v2.1.6 h1:igy0q9JcqovoFXFx/XjtU8sHVhcUHavPj2sA3EoKJUE= go.maximumdirect.net/ckconfig v0.9.0/go.mod h1:yGjFVr2UzjJjiwDdMwsKehuQfvvtv7rTEOIk5NQOY00=
github.com/yuin/goldmark/v2 v2.1.6/go.mod h1:G6M4/qOFtfn01/o14BU1UR2Lo5N3S9Qo7xCuz/sHjGQ= go.maximumdirect.net/ckprompt v0.10.0 h1:t2UyWSke+bWH9aTDrw5/bteD+TO0y5LD0NWw0y2KniQ=
go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4= go.maximumdirect.net/ckprompt v0.10.0/go.mod h1:vx8lZnelASctQtyxY2yV4PuTZfLpE9EqDa+LPj3+SHM=
go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0= go.maximumdirect.net/commandkit v0.7.0 h1:toLDGhHoVe6gBX5HWuzQ/Joz0cBqEhJXolW21m3axBk=
golang.org/x/mod v0.40.0 h1:hUv+3cXcdRHz08UmSiOob7sadHig73uo5bkXxQ/tvUs= go.maximumdirect.net/commandkit v0.7.0/go.mod h1:sVp3JXKpm2YrP4Ie8Q3nWmQgwBdPN8uO+wQU72erDns=
golang.org/x/mod v0.40.0/go.mod h1:0/weTWkPWGBikyTWAX3dkjVztMmBA5hM0DH6BElSupE= go.maximumdirect.net/configkit v1.2.1 h1:f+/6WjNl6CULbMr6ZSVwi4aty9rmuDfJlvpeU7I+HZM=
golang.org/x/text v0.14.0 h1:ScX5w1eTa3QqT8oi6+ziP7dTV1S2+ALU0bI+0zXKWiQ= go.maximumdirect.net/configkit v1.2.1/go.mod h1:ewu6blSokUDCMovy8JBXAdXRikGmlHXAQpFghnPWRfs=
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU= 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 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 package cli
import ( import (
"bytes"
"context"
"crypto/rand"
"encoding/hex"
"errors" "errors"
"fmt" "fmt"
"io"
"strings"
"sync" "sync"
"time"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/chunking" "gitea.maximumdirect.net/eric/audita/v4/internal/core/normalization"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/config" "gitea.maximumdirect.net/eric/audita/v4/internal/core/outputschema"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/diagnostics" "gitea.maximumdirect.net/eric/audita/v4/internal/core/reporting"
coreio "gitea.maximumdirect.net/eric/audita/v3/internal/core/io" "gitea.maximumdirect.net/eric/audita/v4/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/normalization" "gitea.maximumdirect.net/eric/audita/v4/internal/framework/llm"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/outputschema" "gitea.maximumdirect.net/eric/audita/v4/internal/framework/preflight"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/redaction" "gitea.maximumdirect.net/eric/audita/v4/internal/framework/runner"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/reporting" "go.maximumdirect.net/ckconfig"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema" commandkit "go.maximumdirect.net/commandkit"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/contracts" ck "go.maximumdirect.net/configkit"
"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"
) )
func runProcess(ctx context.Context, args []string, stdout, stderr io.Writer) int { // processResult carries the runner's transcript and ordinary report facts.
input, help, err := parseConfigInput("process", args, stderr) type processResult struct {
if err != nil { Transcript *schema.Transcript
fmt.Fprintf(stderr, "audita process: %s\n", configInputError(err)) Snapshot reporting.Snapshot
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
}
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)
}
}
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})
if err != nil {
fmt.Fprintf(stderr, "audita process: %s\n", llm.RedactError(err, cfg))
return 2
}
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
}
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
}
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 { func runProcess(inv commandkit.Invocation, input processInput) commandkit.Outcome {
cfg config.Config loaded, err := loadProcessInputs(inv.Context, input, inv.ReportingMode())
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 { if err != nil {
return diagnostics.ReportBundle{}, err if canceled := inv.Context.Err(); canceled != nil && !errors.Is(err, canceled) {
err = errors.Join(err, canceled)
} }
recoveriesYAML, err := reporting.YAML(snapshot.RecoveriesDocument(), secrets...) 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)
}
prepared, err := prepareProcess(inv.Context, input, loaded, inv.Reporter().Output())
if err != nil { if err != nil {
return diagnostics.ReportBundle{}, err var selection *preflight.SelectionError
if inv.Context.Err() == nil && errors.As(err, &selection) {
return commandkit.Usage(err.Error()).WithCause(err)
} }
return diagnostics.ReportBundle{Errors: errorsYAML, Recoveries: recoveriesYAML, return commandkit.Failure(err.Error()).WithCause(err)
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 { defer prepared.Prepared.Output.Close()
s.reportDiagnosticError(fmt.Errorf("%s: %w", label, err)) var warningsMu sync.Mutex
} warn := func(err error) {
}
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,
})
})
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))
}
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 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))
}
}
func (s *processState) debugPath() string {
if s.debugDir == 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 { if err == nil {
return return
} }
message := "debug " + llm.RedactError(err, s.cfg) warningsMu.Lock()
s.debugMu.Lock() prepared.Prepared.Warnings = append(prepared.Prepared.Warnings, err)
defer s.debugMu.Unlock() warningsMu.Unlock()
s.debugWarnings = append(s.debugWarnings, message) }
debug := prepared.Prepared.Debug
if debug != nil {
warn(debug.WriteSourceTranscript(loaded.Source, loaded.RawTranscript))
}
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,
})
transcript := loaded.Source.Canonical()
loaded.Source = nil
normalized, summary := normalizer.Normalize(transcript)
if debug != nil {
warn(debug.WriteNormalizedTranscript(normalized))
warn(debug.WriteNormalizationSummary(summary))
}
if err := inv.Context.Err(); err != nil {
return finishProcess(inv, input, prepared, reporting.Snapshot{}, nil, &runner.ExecutionFailure{Phase: "normalization", Cause: 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)
}
// 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 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 ( import (
"context" "context"
"flag"
"fmt" "fmt"
"io" "io"
"gitea.maximumdirect.net/eric/ReleaseKit/buildinfo" commandkit "go.maximumdirect.net/commandkit"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/schema"
"gitea.maximumdirect.net/eric/audita/v3/internal/framework/llm"
) )
func sourceToCanonicalTranscript(source *schema.SourceTranscript) *schema.Transcript { // Run executes the application with the provided arguments and streams.
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.
func Run(ctx context.Context, args []string, stdout, stderr io.Writer) int { func Run(ctx context.Context, args []string, stdout, stderr io.Writer) int {
if len(args) == 0 { app, err := buildApplication()
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)
if err != nil { if err != nil {
fmt.Fprintf(stderr, "audita config validate: %s\n", configInputError(err)) fmt.Fprintln(stderr, 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 1
} }
return 2 return app.Execute(ctx, args, commandkit.Streams{Out: stdout, Err: stderr}).Status
}
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)
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")
} }

View File

@@ -3,74 +3,113 @@ package cli
import ( import (
"bytes" "bytes"
"context" "context"
"errors"
"os" "os"
"path/filepath" "path/filepath"
"strings" "strings"
"testing" "testing"
commandkit "go.maximumdirect.net/commandkit"
) )
func writeRuntimeErrorConfig(t *testing.T, operatorDocument string) string { func writeRuntimeErrorConfig(t *testing.T, operatorDocument string) string {
t.Helper() t.Helper()
dir := t.TempDir() 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") 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" for name, body := range map[string]string{"config.yml": "version: 3\n", "prompts.yml": operatorDocument} {
if err := os.WriteFile(main, []byte(configText), 0600); err != nil { if err := os.WriteFile(filepath.Join(dir, name), []byte(body), 0600); err != nil {
t.Fatal(err) t.Fatal(err)
} }
if err := os.WriteFile(filepath.Join(profiles, "operator.yml"), []byte(operatorDocument), 0600); err != nil {
t.Fatal(err)
} }
return main return main
} }
func TestConfigCommandsClassifyOperatorPromptErrorsAsInputErrors(t *testing.T) { func TestResourceCommandsRejectInvalidOperatorPrompts(t *testing.T) {
t.Setenv("AUDITA_TEST_PROVIDER_KEY", "synthetic-cli-redaction-secret")
definitions := map[string]string{ definitions := map[string]string{
"malformed operator YAML": "profiles:\n proposal: [\n", "malformed operator YAML": "profiles: [\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", "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": "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", "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 { for name, document := range definitions {
name string t.Run(name, func(t *testing.T) {
args []string
}{
{name: "validate", args: []string{"config", "validate"}},
{name: "print effective", args: []string{"config", "print-effective", "--view", "profiles"}},
}
for definition, document := range definitions {
for _, command := range commands {
t.Run(definition+"/"+command.name, func(t *testing.T) {
main := writeRuntimeErrorConfig(t, document) main := writeRuntimeErrorConfig(t, document)
args := append(append([]string(nil), command.args...), "--config", main)
var stdout, stderr bytes.Buffer var stdout, stderr bytes.Buffer
if code := Run(context.Background(), args, &stdout, &stderr); code != 2 { if code := Run(context.Background(), []string{"promptkit", "list", "prompts", "--config", main}, &stdout, &stderr); code == 0 {
t.Fatalf("exit=%d, stdout=%q, stderr=%q", code, stdout.String(), stderr.String()) t.Fatalf("invalid resource accepted: stdout=%q stderr=%q", 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) { func TestUnreadableCompanionReturnsOperationalFailure(t *testing.T) {
t.Setenv("AUDITA_TEST_PROVIDER_KEY", "synthetic-cli-redaction-secret") main := writeRuntimeErrorConfig(t, "profiles: []\n")
main := writeRuntimeErrorConfig(t, "profiles:\n proposal:\n backend: offline\n model: local-model\n") companion := filepath.Join(filepath.Dir(main), "prompts.yml")
commands := [][]string{ if err := os.Chmod(companion, 0); err != nil {
{"config", "validate", "--config", main}, t.Fatal(err)
{"config", "print-effective", "--config", main, "--view", "profiles"},
} }
for _, args := range commands { if _, err := os.ReadFile(companion); !errors.Is(err, os.ErrPermission) {
ctx, cancel := context.WithCancel(context.Background()) t.Skipf("file permissions do not prevent reads: %v", err)
cancel() }
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 var stdout, stderr bytes.Buffer
if code := Run(ctx, args, &stdout, &stderr); code != 1 { code := Run(context.Background(), append(args, "--config", main), &stdout, &stderr)
t.Fatalf("args=%v exit=%d, stdout=%q, stderr=%q", args, code, stdout.String(), stderr.String()) 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" "strings"
"testing" "testing"
"gitea.maximumdirect.net/eric/ReleaseKit/buildinfo" "go.maximumdirect.net/releasekit/buildinfo"
) )
func TestVersionCommandRunsWithoutApplicationSetup(t *testing.T) { func TestVersionCommandRunsWithoutApplicationSetup(t *testing.T) {
@@ -30,12 +30,10 @@ func TestVersionCommandHelp(t *testing.T) {
args []string args []string
want 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: "help version", args: []string{"help", "version"}, want: "audita version"},
{name: "short flag", args: []string{"version", "-h"}, want: "audita version"}, {name: "short flag", args: []string{"version", "-h"}, want: "audita version"},
{name: "long flag", args: []string{"version", "--help"}, 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) { t.Run(test.name, func(t *testing.T) {
var stdout, stderr bytes.Buffer var stdout, stderr bytes.Buffer

View File

@@ -2,8 +2,9 @@ package chunking
import ( import (
"fmt" "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. // 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] totalTokens += segmentTokens[i]
} }
minPossibleSections := c.calculateMinPossibleSections(segmentTokens)
var desiredSections int
useExplicitTarget := false
if c.config.TargetSections != nil { if c.config.TargetSections != nil {
desiredSections = *c.config.TargetSections target := *c.config.TargetSections
useExplicitTarget = true if target <= 0 {
if desiredSections <= 0 { return nil, fmt.Errorf("target_sections must be positive, got %d", target)
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)
} }
return c.buildSectionsWithExplicitTarget(transcript.Segments, segmentTokens, target, ceilDiv(totalTokens, target))
} }
targetTokensPerSection := ceilDiv(totalTokens, desiredSections) desiredSections := ceilDiv(totalTokens, c.config.MaxSectionTokens)
if useExplicitTarget { desiredSections = max(desiredSections, c.calculateMinPossibleSections(segmentTokens), 1)
return c.buildSectionsWithExplicitTarget( desiredSections = min(desiredSections, len(transcript.Segments))
transcript.Segments, return c.buildSectionsBalanced(transcript.Segments, segmentTokens, ceilDiv(totalTokens, desiredSections)), nil
segmentTokens,
desiredSections,
targetTokensPerSection,
)
}
return c.buildSectionsBalanced(transcript.Segments, segmentTokens, targetTokensPerSection), nil
} }
// validateTargetSections checks if the target section count is achievable. // InfeasibleTargetError indicates that a requested count cannot partition the
func (c *Chunker) validateTargetSections(target int, segmentTokens []int) error { // normalized segments into nonempty, token-bounded sections.
// Maximum possible sections: limited by segment count type InfeasibleTargetError struct {
maxPossibleSections := len(segmentTokens) Target int
SegmentCount int
MinimumSections int
MaxSectionTokens int
}
if target > maxPossibleSections { func (e *InfeasibleTargetError) Error() string {
return fmt.Errorf( if e.Target > e.SegmentCount {
"target_sections (%d) is impossible: cannot have more sections than segments (%d)", return fmt.Sprintf("target_sections (%d) is impossible: cannot have more sections than segments (%d)", e.Target, e.SegmentCount)
target, maxPossibleSections)
} }
return fmt.Sprintf("target_sections (%d) is impossible: need at least %d sections to respect max_section_tokens (%d)",
// Minimum possible sections: each segment must fit within max bounds e.Target, e.MinimumSections, e.MaxSectionTokens)
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
} }
// buildSectionsBalanced creates sections with a deterministic single-pass policy. // buildSectionsBalanced creates sections with a deterministic single-pass policy.
@@ -245,59 +215,63 @@ func (c *Chunker) calculateMinPossibleSections(segmentTokens []int) int {
return sections 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( func (c *Chunker) buildSectionsWithExplicitTarget(
segments []schema.Segment, segments []schema.Segment,
segmentTokens []int, segmentTokens []int,
desiredSections int, target, targetTokensPerSection int,
targetTokensPerSection int,
) ([]Section, error) { ) ([]Section, error) {
n := len(segments) n := len(segments)
cursor := 0 if target > n {
sections := make([]Section, 0, desiredSections) 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}
}
for sectionIdx := 0; sectionIdx < desiredSections; sectionIdx++ { sections := make([]Section, 0, target)
if cursor >= n { 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 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 cursor != n || len(sections) != desiredSections {
return nil, fmt.Errorf(
"target_sections (%d) is impossible under current constraints (got %d sections)",
desiredSections,
len(sections),
)
}
return sections, nil return sections, nil
} }
@@ -308,5 +282,5 @@ func ceilDiv(numerator int, denominator int) int {
if numerator <= 0 { if numerator <= 0 {
return 0 return 0
} }
return (numerator + denominator - 1) / denominator return 1 + (numerator-1)/denominator
} }

View File

@@ -1,10 +1,13 @@
package chunking package chunking
import ( import (
"errors"
"math/bits"
"strconv"
"strings" "strings"
"testing" "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. // 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}) chunker := NewChunker(ChunkingConfig{MaxSectionTokens: 100, MinSectionTokens: 1, TargetSections: &target})
_, err := chunker.ChunkTranscript(makeTranscript(segments)) _, err := chunker.ChunkTranscript(makeTranscript(segments))
if err == nil { var infeasible *InfeasibleTargetError
t.Fatal("expected error for impossible target_sections") 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") { if !strings.Contains(err.Error(), "cannot have more sections than segments") {
t.Fatalf("unexpected error: %v", err) t.Fatalf("unexpected error: %v", err)
@@ -318,14 +322,94 @@ func TestChunkTargetSectionsImpossibleTooFew(t *testing.T) {
) )
_, err := chunker.ChunkTranscript(makeTranscript(segments)) _, err := chunker.ChunkTranscript(makeTranscript(segments))
if err == nil { var infeasible *InfeasibleTargetError
t.Fatal("expected error for impossible target_sections") 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") { if !strings.Contains(err.Error(), "need at least 3 sections") {
t.Fatalf("unexpected error: %v", err) 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) { func TestChunkManySmallSegmentsBalanced(t *testing.T) {
texts := []string{"1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11"} texts := []string{"1", "2", "3", "4", "5", "6", "7", "8", "9", "10", "11"}
segments := makeSegments(texts) 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 package chunking
import ( import (
"strings"
"unicode" "unicode"
) )
@@ -24,24 +23,39 @@ func NewSimpleTokenEstimator() *SimpleTokenEstimator {
// This implementation uses a simple heuristic: count words and punctuation as tokens. // This implementation uses a simple heuristic: count words and punctuation as tokens.
// The estimate is deterministic and stable for the same input text. // The estimate is deterministic and stable for the same input text.
func (e *SimpleTokenEstimator) EstimateTokens(text string) int { func (e *SimpleTokenEstimator) EstimateTokens(text string) int {
if text == "" { var count TokenCount
return 0 count.Add(text)
} return count.Estimate()
}
// Simple heuristic: split on whitespace and count non-empty segments // CountComponents returns unrounded counts for budgets composed from fragments.
words := strings.Fields(text) func (e *SimpleTokenEstimator) CountComponents(text string) (words, punctuation int) {
tokenCount := len(words) var count TokenCount
count.Add(text)
return count.words, count.punctuation
}
// Add some estimate for punctuation that might be separate tokens // TokenCount can be copied and extended with adjacent text fragments.
punctuationCount := 0 type TokenCount struct {
words, punctuation int
inWord bool
}
func (c *TokenCount) Add(text string) {
for _, r := range text { for _, r := range text {
nonspace := !unicode.IsSpace(r)
if nonspace && !c.inWord {
c.words++
}
c.inWord = nonspace
if unicode.IsPunct(r) && r != '\'' && r != '-' && r != '_' { if unicode.IsPunct(r) && r != '\'' && r != '-' && r != '_' {
punctuationCount++ c.punctuation++
} }
} }
}
// Rough estimate: each word is a token, plus half the punctuation as separate tokens func (c TokenCount) Estimate() int {
return tokenCount + (punctuationCount / 2) return c.words + c.punctuation/2
} }
// ConstTokenEstimator returns a constant token count for testing purposes. // ConstTokenEstimator returns a constant token count for testing purposes.

View File

@@ -5,49 +5,65 @@ import (
"strings" "strings"
"time" "time"
ck "gitea.maximumdirect.net/eric/ConfigKit" "gitea.maximumdirect.net/eric/audita/v4/internal/core/modulecatalog"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/modulecatalog" "gitea.maximumdirect.net/eric/audita/v4/internal/core/outputschema"
"gitea.maximumdirect.net/eric/audita/v3/internal/core/outputschema" ck "go.maximumdirect.net/configkit"
) )
const ( const (
DefaultModulesCSV = "glossary,homophones,glossary,spoken_word,grammar"
DefaultTranscriptDescriptionMaxChars = 500 DefaultTranscriptDescriptionMaxChars = 500
DefaultValidationMaxPromptTokens = 2048 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 { type Config struct {
Version int `yaml:"version"` Version int `yaml:"version"`
ProfilesDir string `yaml:"profiles_dir"` Glossaries []string `yaml:"glossaries"`
Backends map[string]Backend `yaml:"backends"` ProtectedTerms []string `yaml:"protected_terms"`
GlossaryCollections map[string]GlossaryCollection `yaml:"glossary_collections"`
LLM LLM `yaml:"llm"` LLM LLM `yaml:"llm"`
Pipeline Pipeline `yaml:"pipeline"` Pipeline Pipeline `yaml:"pipeline"`
Output Output `yaml:"output"` Output Output `yaml:"output"`
Validation Validation `yaml:"validation"` Validation Validation `yaml:"validation"`
Chunking Chunking `yaml:"chunking"` Chunking Chunking `yaml:"chunking"`
Normalization Normalization `yaml:"normalization"` Normalization Normalization `yaml:"normalization"`
Thresholds Thresholds `yaml:"thresholds"`
Context Context `yaml:"context"` Context Context `yaml:"context"`
Reporting Reporting `yaml:"reporting"` Reporting Reporting `yaml:"reporting"`
Diagnostics Diagnostics `yaml:"diagnostics"` Diagnostics Diagnostics `yaml:"diagnostics"`
} }
type Backend struct { type GlossaryCollection struct {
Endpoint string `yaml:"endpoint"` Entries []GlossaryEntry `yaml:"entries"`
Concurrency int `yaml:"concurrency"` }
QueueCapacity int `yaml:"queue_capacity"` type GlossaryEntry struct {
Credential *ck.Secret `yaml:"credential"` 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 { type LLM struct {
ProposalProfile string `yaml:"proposal_profile"` ProposalProfile *string `yaml:"proposal_profile"`
ValidationProfile string `yaml:"validation_profile"` ValidationProfile *string `yaml:"validation_profile"`
CorrectionRepairProfile *string `yaml:"correction_repair_profile"`
CorrectionRepairAttempts int `yaml:"correction_repair_attempts"`
TransientRetries int `yaml:"transient_retries"` TransientRetries int `yaml:"transient_retries"`
RepairAttempts int `yaml:"repair_attempts"` RepairAttempts int `yaml:"repair_attempts"`
OperationTimeout time.Duration `yaml:"operation_timeout"` OperationTimeout time.Duration `yaml:"operation_timeout"`
} }
type Pipeline struct { 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 { type Output struct {
Schema string `yaml:"schema"` Schema string `yaml:"schema"`
@@ -66,17 +82,10 @@ type Normalization struct {
MaxSegmentDuration float64 `yaml:"max_segment_duration"` MaxSegmentDuration float64 `yaml:"max_segment_duration"`
MaxSegmentTokens int `yaml:"max_segment_tokens"` 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 { type Context struct {
Description string `yaml:"description"` Description string `yaml:"description"`
} }
type Diagnostics struct { type Diagnostics struct {
Debug bool `yaml:"debug"`
WorkDir string `yaml:"work_dir"` WorkDir string `yaml:"work_dir"`
} }
type Reporting struct { type Reporting struct {
@@ -86,51 +95,46 @@ type Reporting struct {
func defaults() Config { func defaults() Config {
return Config{ return Config{
ProfilesDir: "profiles", Version: 3,
LLM: LLM{TransientRetries: 2, RepairAttempts: 2, OperationTimeout: 15 * time.Minute}, LLM: LLM{TransientRetries: 2, RepairAttempts: 2, CorrectionRepairAttempts: 1, OperationTimeout: 15 * time.Minute},
Pipeline: Pipeline{Modules: []string{"glossary", "homophones", "glossary", "spoken_word", "grammar"}}, Pipeline: Pipeline{Stages: []Stage{{Module: "glossary"}, {Module: "homophones"}, {Module: "glossary"}, {Module: "spoken_word"}, {Module: "grammar"}}},
Output: Output{Schema: "bare-segments"}, Output: Output{Schema: "bare-segments"},
Validation: Validation{MaxPromptTokens: DefaultValidationMaxPromptTokens}, Validation: Validation{MaxPromptTokens: DefaultValidationMaxPromptTokens},
Chunking: Chunking{MaxSectionTokens: 8192, MinSectionTokens: 2048}, Chunking: Chunking{MaxSectionTokens: 8192, MinSectionTokens: 2048},
Normalization: Normalization{MaxSegmentGap: 4, EllipsisGap: 3.5, MaxSegmentDuration: 60, MaxSegmentTokens: 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: "."}, Reporting: Reporting{Enabled: true, StdoutDir: "."},
Diagnostics: Diagnostics{WorkDir: "/tmp/audita"}, Diagnostics: Diagnostics{WorkDir: "/tmp/audita"},
} }
} }
// Load resolves the selected main file, optional overlay, and explicit setting overrides. const glossaryImports = `config:
// Its result retains safe effective output and provenance for CLI composition. imports:
func Load(source ck.Source, overlay string, overrides ...ck.Override) (*ck.Result[Config], error) { - path: glossary.yml
return ck.Load(source, ck.Options[Config]{ 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, 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]{ 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 { Version: &ck.VersionRule{Path: ck.Keys("version"), Check: func(version ck.Version, v *ck.Validation) error {
if !version.Present || version.Null || version.Text != "2" { if version.Present && (version.Null || version.Text != "3") {
v.Error(ck.Keys("version"), "version 2 is required; see docs/migrations/v2.md") v.Error(ck.Keys("version"), "use application configuration version 3; see docs/migrations/v3.md")
} }
return nil return nil
}}, }},
Resolve: func(c *Config, r *ck.Resolution) error { Resolve: resolveSettings,
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
},
Validate: validate, Validate: validate,
}, },
}) })
@@ -142,24 +146,41 @@ func validate(c *Config, v *ck.Validation) {
v.Error(path, message) v.Error(path, message)
} }
} }
check(strings.TrimSpace(c.ProfilesDir) != "", ck.Keys("profiles_dir"), "profile directory is required") for name, collection := range c.GlossaryCollections {
check(strings.TrimSpace(c.LLM.ProposalProfile) != "", ck.Keys("llm", "proposal_profile"), "proposal profile is required") for i, entry := range collection.Entries {
check(strings.TrimSpace(c.LLM.ValidationProfile) != "", ck.Keys("llm", "validation_profile"), "validation profile is required") path := ck.Keys("glossary_collections", name, "entries").Index(i)
check(c.LLM.TransientRetries >= 0, ck.Keys("llm", "transient_retries"), "retry budget must be non-negative") check(entry.ID != "", path.Key("id"), "entry id must not be empty")
check(c.LLM.RepairAttempts >= 0 && c.LLM.RepairAttempts <= 3, ck.Keys("llm", "repair_attempts"), "repair attempts must be between zero and three") check(entry.Name != "", path.Key("name"), "entry name must not be empty")
check(c.LLM.OperationTimeout > 0, ck.Keys("llm", "operation_timeout"), "operation timeout must be positive") check(entry.Category != "", path.Key("category"), "entry category must not be empty")
check(len(c.Backends) > 0, ck.Keys("backends"), "at least one backend is required") for index, alias := range entry.Aliases {
for id, b := range c.Backends { check(alias != "", path.Key("aliases").Index(index), "alias must not be empty")
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 i, module := range c.Pipeline.Modules { check(entry.Plural == nil || *entry.Plural != "", path.Key("plural"), "plural must not be empty")
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(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.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.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") 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.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.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") 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 validateRuntimeSettings(check func(bool, ck.Path, string), base ck.Path, settings LLM, validation Validation, context Context) {
func ParseModulesCSV(raw string) ([]string, error) { llm := base.Key("llm")
if raw == "" { check(settings.TransientRetries >= 0, llm.Key("transient_retries"), "retry budget must be non-negative")
return []string{}, nil 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")
parts := strings.Split(raw, ",") check(settings.CorrectionRepairProfile == nil || *settings.CorrectionRepairProfile != "", llm.Key("correction_repair_profile"), "correction repair profile must not be empty; use null to clear it")
for i := range parts { check(settings.OperationTimeout > 0, llm.Key("operation_timeout"), "operation timeout must be positive")
parts[i] = strings.TrimSpace(parts[i]) check(settings.ValidationProfile == nil || *settings.ValidationProfile != "", llm.Key("validation_profile"), "validation profile must not be empty; use null to clear it")
if parts[i] == "" { check(validation.MaxPromptTokens > 0, base.Key("validation").Key("max_prompt_tokens"), "validation prompt budget must be positive")
return nil, fmt.Errorf("modules list contains an empty value") check(len(strings.TrimSpace(context.Description)) <= DefaultTranscriptDescriptionMaxChars, base.Key("context").Key("description"), fmt.Sprintf("description must be at most %d bytes after trimming", DefaultTranscriptDescriptionMaxChars))
}
}
return parts, nil
} }

View File

@@ -1,303 +1,198 @@
package config package config
import ( import (
"bytes" "io/fs"
"errors"
"os" "os"
"path"
"path/filepath" "path/filepath"
"reflect"
"strings"
"testing" "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 TestDefaultsAndVersion(t *testing.T) {
result, err := Load(ck.Input{Source: ck.NoSource()}, "")
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, "")
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
c := loaded.Config if result.Config.Version != 3 || len(result.Config.Pipeline.Stages) != 5 {
if c.LLM.ValidationProfile != "proposal" || c.Backends["local"].Concurrency != 1 || c.Backends["local"].QueueCapacity != 1024 { t.Fatalf("defaults: %+v", result.Config)
t.Fatalf("derived settings: %+v %+v", c.LLM, c.Backends)
} }
if !reflect.DeepEqual(c.Pipeline.Modules, []string{"glossary", "homophones", "glossary", "spoken_word", "grammar"}) { path := filepath.Join(t.TempDir(), "config.yml")
t.Fatalf("module order: %v", c.Pipeline.Modules) for _, text := range []string{"version: 2\n", "version: null\n", "version: invalid\n"} {
} if err := os.WriteFile(path, []byte(text), 0644); err != nil {
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) t.Fatal(err)
} }
}) if _, err := Load(ck.Input{Source: ck.File(path)}, ""); err == nil {
t.Fatalf("accepted %q", text)
} }
}
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 len(empty.Config.Pipeline.Stages) != 0 {
t.Fatal("empty pipeline was not preserved")
}
} }
func TestOverlayOverrideAndInheritance(t *testing.T) { func TestMainContextImportsAndOverlay(t *testing.T) {
dir := t.TempDir() 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) t.Fatal(err)
} }
main := filepath.Join(dir, "config.yml") for name, contents := range map[string]string{
if err := os.WriteFile(main, []byte(base), 0600); err != nil { "main.yml": "version: 3\nconfig:\n imports:\n - path: fragment.yml\noutput:\n schema: bare-segments\n",
t.Fatal(err) "fragment.yml": "context:\n description: imported\n",
} "overlays/selected.yml": "context:\n description: overlay\n",
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) { if err := os.WriteFile(filepath.Join(dir, name), []byte(contents), 0644); err != nil {
t.Errorf("inherited field %s is not explicit", path.String()) t.Fatal(err)
} }
} }
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"})
overridden, err := loadText(strings.Replace(text, " extends: base\n", " extends: base\n concurrency: 2\n", 1), "")
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
if got := overridden.Config.Backends["local"].Concurrency; got != 2 { if info, ok := result.Metadata().Lookup(ck.Keys("context", "description")); !ok || info.Origin.Layer != ck.LayerCLI {
t.Fatalf("child concurrency override: %d", got) t.Fatalf("override origin = %+v", info)
} }
if got := overridden.Config.Backends["local"].QueueCapacity; got != 0 { if result.Config.Context.Description != "override" {
t.Fatalf("inherited zero queue capacity: %d", got) 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 TestSiblingInheritanceUsesSelectedOverlay(t *testing.T) { func TestDiscoveryAndSelectedFailure(t *testing.T) {
dir := t.TempDir() first, second := t.TempDir(), t.TempDir()
if err := os.Mkdir(filepath.Join(dir, "overlays"), 0700); err != nil { search := ck.Searches(ck.SearchDirectory(first), ck.SearchDirectory(second))
t.Fatal(err) load := func() (*ck.Result[Config], error) {
return Load(ck.Input{Source: ck.SearchConfig("audita", search)}, "")
} }
main := filepath.Join(dir, "config.yml") result, err := load()
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)
}
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")
if err != nil { if err != nil {
t.Fatal(err) t.Fatal(err)
} }
child := loaded.Config.Backends["local"] for _, source := range result.Sources() {
if child.Endpoint != "https://overlay.invalid/v1" || child.Concurrency != 2 || child.QueueCapacity != 0 { if source.Layer == ck.LayerMain {
t.Fatalf("overlay inheritance and child override: %+v", child) 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 TestSiblingInheritanceDoesNotBypassBackendValidation(t *testing.T) { 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 { for _, tc := range []struct {
name string name, text string
text string valid bool
}{ }{
{ {"nullable selections", "glossaries: null\nprotected_terms: []\nllm:\n validation_profile: null\n", true},
name: "invalid inherited parent setting", {"repeated modules", "pipeline:\n stages:\n - module: grammar\n - module: grammar\n", true},
text: `version: 2 {"removed backends", "backends: {}\n", false},
backends: {"removed debug", "diagnostics:\n debug: true\n", false},
base: {"unknown module", "pipeline:\n stages:\n - module: unknown\n", false},
endpoint: https://base.invalid/v1 {"invalid chunk limit", "chunking:\n target_sections: 0\n", false},
concurrency: 0 {"null group", "llm: null\n", false},
local: {"zero budgets", "llm:\n transient_retries: 0\n repair_attempts: 0\n", true},
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
`,
},
} { } {
t.Run(tc.name, func(t *testing.T) { t.Run(tc.name, func(t *testing.T) {
if _, err := loadText(tc.text, ""); err == nil { if err := os.WriteFile(path, []byte(tc.text), 0644); err != nil {
t.Fatal("invalid backend concurrency accepted") 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