Files
notarius/docs/roadmap/remediation.md

608 lines
33 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Native Migration Review Remediation
## Scope And Baseline
Review date: 2026-11-22.
Reviewed commit: `75444b8ef300ca8efee57d7a2271d21ce258b49c`.
Integration follow-up baseline: `fd134e85e54c6e0f74aab5c77df5bada7c1b1e6a`.
The follow-up baseline adds only the initial review findings; application code
is unchanged between these revisions.
Algorithmic follow-up baseline: `fdaf39162b46b528fddcd8a4cad18a09e1daf661`.
Only this findings document changed after the application baseline above.
This review followed the 46 stages in [the implementation plan](implementation.md)
against the [native migration target](promptkit.md), current owning code,
focused tests, maintained examples, and canonical documentation. The migration
is substantially complete. Findings 1–2 come from the initial review. Findings
3–5 come from an integration pass. Findings 6–9 and the complexity note on
Finding 1 come from a stage-ordered algorithmic pass. The latter are refactoring
opportunities for consideration, not measured production bottlenecks or new
performance guarantees. None calls for another compatibility layer or application
execution abstraction. The evidence below describes the reviewed baselines;
per-finding completion markers record the subsequent remediation work.
## Finding 1: Retain Genuine Native Timeouts During Concurrent Error Selection
**Status: Complete.** Operational deadlines participate in linear minimum
selection; sibling cancellation noise and authoritative caller cancellation are
preserved. Pipeline tests and race checks pass.
Priority: P2. Relevant stages: 10, 25, 37, and 46.
### Evidence And Impact
[`selectRunError`](../../internal/framework/pipeline/runner_concurrent.go),
lines 398–428 at the reviewed revision, suppresses every error matching
`context.Canceled` or `context.DeadlineExceeded` when any other failure is
available. This retained cancellation filter does not distinguish a canceled
sibling from an independently failed native operation.
A native PromptKit operation timeout matches both
`promptkit.ErrOperationTimeout` and `context.DeadlineExceeded`, even when the
caller context remains active. Consequently, a genuine timeout in an earlier
stage/lane/chunk scope is discarded in favor of a later non-context error,
rather than participating in the runner's stable scope ordering. The returned
cause then loses that native timeout identity.
The producer helper itself handles this distinction correctly; the gap is at
the concurrent runner's final selection boundary. A temporary review test used
the real PromptKit engine with a fake provider, obtained an actual native
operation timeout with an active caller, and supplied it as the earlier of two
scoped failures. The selector returned the later error instead. Existing helper
timeout coverage does not exercise this aggregation boundary.
### Required Change
Refine error selection so genuine operational deadline/timeout failures remain
eligible for the existing stable scope ordering. Distinguish them from
runner-induced sibling cancellation using the relevant context state and native
causes. Preserve authoritative caller cancellation and suppression of derivative
cancellation noise. An active caller's deadline-shaped operation failure must
not be discarded merely because it matches `context.DeadlineExceeded`.
Keep this a small runner correction; no new timeout controls, retry loop, or
application error taxonomy is needed.
### Acceptance
- With an active caller, an earlier-scoped native operation timeout and a later
ordinary failure select the timeout and retain its native `errors.Is` identity.
- A non-caller provider deadline also remains a genuine operational failure.
- Caller cancellation/deadline and runner-induced sibling cancellation retain
their intended precedence/noise handling.
- Ordinary multi-failure ordering and worker cancellation/draining remain intact.
- Add focused behavioral coverage at the runner error-selection boundary, using
the existing native timeout fixture where useful. Run the pipeline tests and
their concurrency/race checks.
### Algorithmic Follow-up: Select A Minimum Instead Of Sorting
With `E` collected errors, the current selector comparison-sorts all eligible
records by `(stage, lane, chunk)` solely to return the first. It performs
`O(E log E)` comparisons; stable sorting can also incur additional superlinear
data movement. After eligibility classification, a minimum scan takes `O(E)`
comparisons and constant auxiliary space; error-chain classification costs remain
separate. Keep the first occurrence on equal keys, matching stable-sort behavior.
This can accompany the correctness
fix without changing error precedence or cancellation semantics. Its practical
impact is smaller than the document/cache indexing findings below.
## Finding 2: Narrow The Documented Empty-Validator-Chain Guarantee
**Status: Complete.** Architecture, configuration, pipeline internals, and the
active plan now distinguish intrinsic checks from configurable citation checks.
Documentation links and whitespace were checked; runtime behavior is unchanged.
Priority: P2. Relevant stages: 11, 38, 39, and 42.
### Evidence And Impact
Three current documents make source checking sound unconditional:
- [Architecture policy](../policy/architecture.md), lines 229–232: intrinsic
codec/source correctness still applies with an empty chain.
- [Configuration reference](../config.md), lines 350–356: intrinsic typed
codec/source checks remain with an empty configured chain.
- [Pipeline internals](../internal/pipeline.md), lines 75–77: an empty chain
cannot remove intrinsic source-addressing checks.
Intrinsic durable-codec validation does remain. However, ordinary artifact
checks that cited units exist in the current source or lie within an extraction
chunk are supplied by the configured source-reference validators; final artifact
serialization does not independently perform those checks. See
[`serializeArtifact`](../../internal/framework/pipeline/runner_typed.go) and
the configured [candidate assessor](../../internal/framework/pipeline/candidate_assessment.go).
A temporary offline native-CLI probe configured `dnd/spells` extraction and
`noop` normalization with `validators: []`, disabled cache use, and supplied a
schema-valid spell citation to unit 999 against a transcript containing only
unit 1. The command succeeded and published that citation. This does not show a
failure of the default validator chains: the probe explicitly replaced them.
It demonstrates that the broad documented guarantee is stronger than the
implemented configurable validation boundary.
### Required Change
Align the three documents with the actual, selected boundary. Distinguish:
- intrinsic durable-codec/schema validation;
- source-document validation and chunk-plan materialization;
- checks a particular module necessarily performs while interpreting,
constructing fallback, or decoding a cache hit; and
- artifact citation existence/containment checks supplied by configured
validators.
State that an explicit empty/replacement chain can omit those ordinary artifact
source-reference checks. Link to the canonical default-chain/configuration
description rather than repeating detailed validator inventories.
Preserve operator replacement of validator chains. Do not add a mandatory
artifact validator, prohibit empty chains, or make every codec consult the
source document merely to satisfy the stronger wording. Those would expand the
requested contract. The Stage 11 completion summary's claim of mandatory final
codec/source checks should be qualified consistently while the active plan is
retained.
### Acceptance
- The architecture, configuration reference, pipeline guide, and active plan
distinguish unconditional codec checks from configurable citation validation.
- They do not imply that disabling validators disables source parsing,
materialization, or necessary module/fallback/cache construction checks.
- Existing default chains, explicit chain replacement, and runtime behavior
remain unchanged.
- Review related current documentation for the same overbroad claim. No new
prose-snapshot or mandatory-source-validation test is needed for this
documentation correction.
## Finding 3: Rebind Cached Scene Identity To The Current Chunk Plan
**Status: Complete.** Scene hits require one exact current-range scene and
reattach its current ordinal identity without model work or reassessment.
Expansion/collapse integration regressions and scene-module tests pass.
Priority: P1. Relevant stages: 11, 23, 27–29, and 37.
### Evidence And Impact
The new message-content cache interacts incorrectly with the existing
position-derived scene identity:
- [`MaterializeChunkPlan`](../../internal/core/source/chunk_plan.go), lines
169–179, renders only source units into chunk content, while assigning
`chunk-000001`, etc. from the range's position in the plan.
- [Scene extraction](../../internal/modules/dnd/extract/scenedescriptions/extractor.go)
deterministically attaches the current chunk ID and range in `mapResponse`.
The model does not supply this identity, and the ID is not rendered into the
initial scene-description messages.
- [`artifactProducerCache`](../../internal/framework/pipeline/runner_cache.go),
lines 21–37, decodes a hit and checks cited source units, but does not rebind
its scene identity. The hit bypasses extraction interpretation and assessment.
Changing an earlier scene boundary can therefore renumber an unchanged later
scene without changing that later scene's prompt hash. Its old accepted artifact
is a legitimate content-key hit, but its stored scene ID belongs to the old plan.
A temporary native-CLI integration probe used real scene planning, extraction,
merging, normalization, default validators, and a filesystem cache. The chunk
binding used `cache: refresh`; scene extraction used ordinary `auto`. The fake
provider returned these two valid plans for the same three-unit transcript:
1. `[1–2], [3]`, followed by `[1], [2], [3]`: the second run failed normalization
with `scene ID "chunk-000002" has conflicting records`.
2. The reverse change: the second run succeeded but published IDs
`chunk-000001` and `chunk-000003` for a two-chunk plan. The last ID should have
been `chunk-000002`.
Both cases pass with invocation-wide cache bypass. The unchanged suffix was
reused in the failing cases, as confirmed by provider-call counts. This is not
an invalid generated plan or intentionally skipped semantic revalidation.
The stale ID also conflicts with the existing [scene registry's exact match](../../internal/modules/dnd/scenedescriptions/registry/registry.go):
combat/enemy consumers require both the current chunk ID and range, so a stale
scene can become unavailable classification and suppress downstream extraction.
### Required Change
Add the missing current-operation adaptation at the scene cache-hit boundary.
For a usable single-scene artifact describing the exact current range,
deterministically reattach the current chunk identity while retaining its accepted
kind/title/summary. If a cached artifact cannot be safely adapted, treat it as an
unusable miss before returning it as accepted work.
Keep domain-specific adaptation with the scene module, using the supplied typed
cache collaboration or a small extension to that boundary if needed. Preserve
the content-only native cache key and no-semantic-reassessment policy. Do not
render an internal scene ID into the prompt, add a partition fingerprint/key
dimension, restore canonical source-only chunking, or ask the model to copy IDs.
Review other current cached artifacts for equivalent operation-derived fields;
do not invent a generic identity framework for families that do not need one.
### Acceptance
- Repartitioning earlier units can move an unchanged later scene to a different
chunk ordinal without duplicate or stale scene IDs in the published artifact.
- Current scene IDs/ranges match the chunk map and remain usable by the existing
combat/enemy eligibility resolver.
- The unchanged scene can reuse its accepted semantic content without another
model call or validator assessment when deterministic adaptation is safe.
- Wrong-range, multi-scene, or otherwise unusable entries are not silently
rebound into valid-looking scenes; they miss normally.
- Add assembled two-run expansion/collapse coverage using the existing native
fake-provider/cache setup, and retain ordinary same-plan hit coverage.
## Finding 4: Bound Framework-Generated Fallback Diagnostic Messages
**Status: Complete.** Framework fallback/cache samples share bounded UTF-8
rendering without changing full outcome evidence or module diagnostic checks.
Multibyte/invalid-UTF-8 regressions and a typed spell CLI fallback probe pass.
Priority: P2. Relevant stages: 9, 11, 24, 29, and 34.
### Evidence And Impact
[`FinishProducerFailure`](../../internal/framework/pipeline/producer_outcome.go)
retains the complete failure text in `ProducerOutcome.FallbackReason` after a
supported permissive fallback is successfully constructed.
[`operationDiagnosticGroups`](../../internal/framework/pipeline/runner_operation.go),
lines 51–58, copies that text unchanged into a framework-generated warning sample.
The existing [diagnostic contract](../../internal/framework/contracts/diagnostics.go)
requires valid UTF-8 and a maximum sample-message size of 4096 bytes.
Native errors and joined assessment errors are not bounded diagnostic samples.
Even individually bounded domain validator messages can exceed the sample limit
after joining several findings and adding validator context. The new fallback
bridge thus creates invalid diagnostics from otherwise valid operation outcomes.
A temporary offline native-CLI probe ran a minimal spell pipeline in permissive
mode with a fake provider returning a long ordinary error. The valid empty spell
fallback was constructed, but the run then failed with
`producer diagnostic 0: diagnostic sample 0: diagnostic sample message exceeds maximum length`.
The failure occurs even with ordinary visibility hiding optional warnings.
### Required Change
Render the framework's fallback warning into a bounded, valid-UTF-8 sample before
promoting it. Reuse or factor the small bounding behavior already present in
[`producerCacheObserver`](../../internal/framework/pipeline/runner_cache.go)
rather than adding a second diagnostic system.
Bound only the generated diagnostic sample, leaving the original error/outcome
text and requested evidence unchanged. This is operator diagnostic presentation,
not model correction guidance. Preserve validation of module-supplied diagnostics;
do not raise/remove the existing cap or suppress genuine malformed-module
contracts to work around the framework's own unbounded sample.
### Acceptance
- A supported permissive fallback still publishes qualified output when its
native or aggregated-assessment cause exceeds the diagnostic sample limit.
- The generated warning is nonblank, bounded, and valid UTF-8, including at a
multibyte truncation boundary.
- Strict handling, caller cancellation, fallback counting/reuse exclusion,
full requested evidence, and module-diagnostic validation remain unchanged.
- Add focused fallback-to-diagnostic integration coverage, including a real
typed producer path with a fake long native error. No model retry is added.
## Finding 5: Remove The Disconnected Legacy LLM Error Contract
**Status: Complete.** Removed the unused legacy error taxonomy and its self-test;
current execution retains native PromptKit errors and application assessment/
capture errors. Contracts, pipeline, CLI, and module integration tests pass.
Priority: P3. Relevant stages: 8, 24, 35, and 44.
### Evidence And Impact
At the reviewed baseline, `internal/framework/contracts/errors.go` still
defines the pre-migration `ErrInvalidStructuredOutput`, `ErrLLMCapacityExceeded`,
`ErrLLMGeneration`, `LLMGenerationError`, constructors, and copied failure/attempt
metadata. Current producers and validators retain native PromptKit errors instead.
Graph/code searches find this old taxonomy only in that file and its
self-test (`internal/framework/contracts/errors_test.go`), not in an active
application consumer.
This is leftover contract surface from the removed adapter, not a second active
execution path. It nevertheless presents obsolete sentinels and metadata accessors
as available framework conventions, although matching actual native failures
against them no longer works. Stage 35's hard-cutover cleanup is incomplete here.
### Required Change And Acceptance
Remove the unused legacy error definitions and their self-test. Keep native
`errors.Is`/`errors.As` behavior and the separate, actively used application
assessment/capture error types. Do not bridge native errors into these retired
sentinels or add aliases for compatibility. Verify no current callers remain and
run contracts, pipeline, CLI, and module integration tests after removal.
## Finding 6: Use Indexed Source Validation In The Chunk-Plan Hot Path
**Status: Complete.** Document validation builds one unit-position map, and plan
materialization reuses checked endpoints without rescanning or duplicate
framework validation. Source, chunk-map, and pipeline tests cover retained
ordering, ownership, malformed-input behavior, and nonmonotonic IDs.
Priority: P2. Relevant stages: 16, 24, 28–29, and 37.
### Evidence And Complexity
The supporting [source validation code](../../internal/core/source/validation.go)
predates this migration, but the new chunk-plan assessment/cache path repeatedly
uses it. `ValidateDocument`, lines 95–101, validates each unit's self-reference
with `ValidateRef`. That helper resolves both endpoints through the linear
`UnitIndex` scan. For a valid document of `N` units, the second validation pass
alone makes `2 * (1 + ... + N) = N(N+1)` unit-ID comparisons: `Theta(N^2)` work.
[`ValidateChunkPlan` and `MaterializeChunkPlan`](../../internal/core/source/chunk_plan.go)
also repeatedly scan the source for each of `C` ranges. A materialization thus
performs `O(N^2 + CN)` source-position work in addition to field checking,
annotation processing, metadata ownership, and payload encoding.
The pipeline's
[`validateAndMaterializeChunkPlan`](../../internal/framework/pipeline/chunk_validation.go)
validates once explicitly and then calls a materializer that validates again.
The [new plan path](../../internal/framework/pipeline/runner_chunk_plan.go)
invokes this during assessment, cache encode/decode, and final delivery. Cached
plans therefore retain this deterministic cost even without inference.
### Potential Refactoring
Use the existing immutable `source.DocumentIndex` for bulk endpoint lookups.
Build/reuse a unit-position map while validating the document, then check its
self-references in linear expected time. Share resolved positions through a
small private validation/materialization helper so materialization does not
rescan endpoints or repeat the same validation unnecessarily. Keep standalone
public validation/materialization entry points correctly validating their inputs.
The attainable position-lookup cost is `O(N + C)` expected work with `O(N)`
index space. Field/payload inspection, annotation canonicalization, metadata
ownership, and JSON encoding remain separate costs. This does not promise linear
total output size: permitted overlapping generic ranges can themselves require
superlinear copied output. Repeated materialization of accepted plans can be
reduced where already-owned checked chunks are available, without retaining a
whole-run ledger or removing necessary current-source checks.
### Preserve And Verify
Preserve document-order semantics for nonconsecutive/nonmonotonic unit IDs,
duplicate/missing/wrong-source/reversed-reference rejection, annotation handling,
deep ownership, and deterministic chunk IDs. Generic plans still permit their
existing gaps/overlaps; D&D coverage rules remain with scene interpretation and
configured validators. No stricter plan format or new size limit is needed.
Use the existing source validation/materialization, chunk-plan operation/cache,
and chunk-map tests. Add only missing behavioral regressions; source inspection
or optional synthetic operation counts can verify the scaling change without
wall-clock thresholds or production data.
## Finding 7: Share A Lazy Source Index Across Artifact Cache Decoders
**Status: Complete.** Run-scoped decoders share a concurrency-safe lazy immutable
index, acquired only when a decoded hit has evidence to check. Concurrent-hit
runner coverage and the pipeline race suite pass; cache modes and usability
checks remain unchanged.
Priority: P2. Relevant stages: 11, 21–22, and 27–28.
### Evidence And Complexity
[`artifactProducerCache`](../../internal/framework/pipeline/runner_cache.go),
line 17, eagerly creates a full `DocumentIndex` for each model-backed operation
whenever a store collaborator exists. It does so before the producer helper
checks bypass/refresh mode, incoming reuse eligibility, or whether a module takes
a legitimate no-model branch. Cold misses also never use the resulting index.
For `J` such operations against `N` source units, this adds `Theta(JN)` index
construction work. With a fixed number of lanes and chunks proportional to
transcript length, that cache-specific term becomes quadratic in `N`.
Concurrent operations can retain `O(min(J,W)N)` cache index entries while waiting
for model work, where `W` is the active worker bound. This is separate from
codec decoding and domain/validator input ownership costs.
### Potential Refactoring
Supply the cache decoders with one run-scoped, immutable source-position index.
Acquire it lazily only when a decoded hit actually needs evidence checks, using
ordinary concurrency-safe initialization. The cache-specific work becomes
`O(N + R)` for all hits, where `R` is the total number of checked cached source
references, with `O(N)` shared index space. Runs with no such checks need not
construct the cache index at all.
This is a small in-memory collaborator, not another persistent cache or source
identity framework. Keep the native message-content key, modes, hit validation,
fallback eligibility, and no-semantic-reassessment policy. Finding 3's scene
identity adaptation is a separate usability concern; shared indexing must not
replace it. Other intentional domain/validator snapshots need not be weakened.
### Preserve And Verify
Retain wrong-source/missing/reversed citation rejection on hits, normal misses,
refresh/bypass/ineligible/no-model behavior, and canceled-hit delivery. Exercise
concurrent hits with the existing cache/runner tests and race checks. Do not add
a public index-build-count contract or a timing-based release gate.
## Finding 8: Index Debug Sensitivity Paths Once
**Status: Complete.** A single historical-path traversal groups marked suffixes
by exact native resource prefix before resource association. Capture regressions
and race checks pass, including mixed root/collection resources, escaped keys,
nested arrays, and native snapshot ownership.
Priority: P3. Relevant stages: 30–31 and 33.
### Evidence And Complexity
[`newRunEvidenceRecorder`](../../internal/cli/run_capture.go), lines 64–91,
collects all `H` historical configuration paths, then scans that full list for
each of `P` profiles/backends across root and collection resources. Prefix
matching therefore performs `O(PH)` work, plus path-string processing. With a
roughly fixed number of fields per resource, `H` grows with `P`, yielding a
quadratic resource-count term.
The caller correctly constructs this recorder only when capture is enabled.
This finding concerns debug startup for large native configurations, not an
unconditional cost on ordinary runs.
### Potential Refactoring
Walk metadata paths once and group relevant sensitive suffixes by their exact
resource prefix. Then associate those groups with root/qualified resource IDs in
one resource traversal. This takes `O(H + P)` path/resource visits, plus processing
the path characters and retained masks, rather than rescanning every unrelated
configuration path for every resource.
Retain native sensitivity classification, correct JSON-pointer segment unescaping,
root/collection distinctions, nested maps/arrays, and nonmutation of native
snapshots. Do not replace exact metadata with credential-like string searches or
broaden omission policy. Use the existing configuration/native capture tests;
add a mixed-resource case only if needed to verify equivalent mask routing.
## Finding 9: Traverse Dense Chunk Results Without Sorting Their Keys
**Status: Complete.** Lane assembly traverses the materializer's dense ordinals
directly, retaining artifact/diagnostic order, fallback counts, and reuse
eligibility without allocating or sorting a temporary key slice. Pipeline
concurrency/ready-job tests and race checks pass.
Priority: P3. Relevant stages: 11, 25, and 37.
### Evidence And Complexity
[`finalizeLaneExtract`](../../internal/framework/pipeline/runner_concurrent.go),
lines 333–349, copies result-map keys to a new slice and sorts them before
assembling the lane. For `C` chunks this costs `O(C log C)` comparisons and
`O(C)` temporary key storage per lane.
The runner's chunks are already assigned contiguous zero-based indexes by
`MaterializeChunkPlan`; successful finalization occurs only after all of that
lane's jobs return. The required order is therefore known, not arbitrary.
### Potential Refactoring And Verification
Traverse the known ordinal range directly for `O(C)` expected map-lookup work
and no temporary key slice, or use an indexed result slice if it simplifies
storage. Keep all artifact/diagnostic ordering, fallback counts, eligibility,
failure handling, cancellation draining, and ready-job scheduling unchanged.
No new chunker restriction is required: dense ordinals are already produced by
the existing materializer, regardless of transcript unit-ID spacing.
The current runner concurrency and ready-job tests cover out-of-order completion
and public result order. Reuse those checks; do not couple tests to a particular
map/slice representation or add another scheduler.
## Review Coverage And Verification
Owning boundaries were inspected in implementation order:
| Stages | Reviewed boundary |
| --- | --- |
| 1–7 | Declared dependencies/notices, native resources/schemas, one ConfigKit result and engine, CommandKit/ckconfig/ckprompt construction and supplied values. |
| 8–11 | Typed production/assessment, full ordered validator chains, native continuation and terminal disposition, runner handoffs and eligibility. |
| 12–24 | All ten D&D extractors, three semantic registry normalizers, scene planning, direct combat-semantic validation, deterministic paths and registration. |
| 25–28 | Ready-job workers, native admission, accepted-artifact cache, prepared handles/initial keys, current-source cache usability and chunk-plan materialization. |
| 29–34 | Domain-only publication, incremental requested capture, offline preflight/inspection, run composition, native reports and failure outcomes. |
| 35–37 | Removal inventory, maintained examples, assembled recovery and subprocess coverage. |
| 38–46 | Successor ADRs and historical-body preservation, canonical references, operations/consumer/migration/internal/integration guides, orientation and final acceptance evidence. |
Checks completed during the initial review:
- `GOWORK=off GOPROXY=off go test ./...` passed.
- `GOWORK=off GOPROXY=off go vet ./...` passed.
- A fresh `GOWORK=off GOPROXY=off go build` to a temporary binary passed.
- `GOWORK=off GOPROXY=off go test -race ./internal/framework/pipeline
./internal/cli` passed.
- Offline executable checks passed for version, minimal/complete pipeline
preflight, and native prompt requirements; native diff check returned its
expected differences status (3).
- The migration diff contains no changes to model-facing JSON schemas or D&D
intrinsic codec schema files. Historical ADR decision bodies are retained;
supersession edits are confined to status descriptions.
- Temporary Go-overlay probes reproduced Findings 1–2 without modifying
repository code or tests. Their deliberately failing assertions are review
evidence, separate from the passing default suite.
The integration follow-up inspected the stage boundaries above against the
retained source/chunk identity, domain codecs/validators, generated references,
diagnostic limits, physical publication, and subprocess contracts. It reused
the earlier full-suite/vet/build/race results only after confirming that the
application code and dependencies were unchanged. Additional checks were:
- `GOWORK=off GOPROXY=off go test ./internal/core/config
./internal/framework/pipeline ./internal/framework/semanticreconcile
./internal/modules/integration ./internal/cli` passed.
- Real native-CLI/fake-provider Go-overlay probes reproduced both directions of
scene repartitioning in Finding 3. Both corresponding bypass controls passed.
- A native-CLI/fake-provider overlay probe reproduced the long-error permissive
fallback failure in Finding 4.
- Graph/code searches confirmed that Finding 5's legacy taxonomy has no active
callers outside its own definition/self-test.
These probes live only in a temporary review directory. No production code,
test, configuration, schema, or existing canonical documentation was changed.
The algorithmic pass followed the same stage order, inspecting actual loop/call
costs rather than treating nested-loop graph metadata as proof of a bottleneck:
- Stages 1–7: native loading/delegation, bounded invocation-selection reuse,
resource/input construction, and absence of a second application load.
- Stages 8–11: candidate serialization/isolation, complete-chain traversal,
native helper control flow, and runner/handoff state.
- Stages 12–24: fixed extraction mappings, bounded reconciliation preparation,
interval coalescing, indexed duplicate/group application, direct validators,
deterministic paths, and the source/materialization costs in Finding 6.
- Stages 25–29: constant-work ready-job dispatch, result/error ordering,
filesystem byte traversal, source-index lifetime, and reuse/auxiliary assembly.
- Stages 30–34: incremental capture, sensitivity-path routing, preflight,
command composition, diagnostics, and publication.
- Stages 35–46: retained/removal boundaries, example/assembled coverage, and
documentation consistency with the algorithms and selected policies above.
Explicitly selected behavior was not reopened: complete validation on every
candidate, fresh normalization application to fixed originals, native growing
history, content-only cache identity, no semantic reassessment on hits, the ready-
job scheduling policy, and self-contained debug records even when content repeats.
The earlier expressly recommended per-handoff output index was also left alone.
Sorting genuinely unordered citations/intervals and collision-safe indexed domain
grouping are not findings merely because they contain loops or comparisons.
Complexity claims in Findings 6–9 follow from the current source and call sites;
they are not throughput estimates. Position-map costs use ordinary expected
hash-map complexity; retained field/payload processing is accounted for separately.
The existing
offline suites for `internal/core/source`, `internal/framework/pipeline`,
`internal/framework/artifactcache`, `internal/framework/semanticreconcile`, and
`internal/cli` passed again. No production workload or performance data was needed,
and no new benchmark, timing assertion, or permanent gate was added.
No live provider inference was performed. This review does not establish
production model quality or performance. Intentional changes such as the hard
configuration/CLI cutover, native retry ownership, content-only cache identity,
no semantic reassessment on hits, explicit permissive fallback, and native
diagnostic visibility are part of the agreed target, not regressions.
## Remediation Completion
All nine findings are addressed in focused commits, with completion markers at
their owning findings above. Final verification after the code changes passed:
- `GOWORK=off GOPROXY=off go test ./...`.
- `GOWORK=off GOPROXY=off go vet ./...`.
- A fresh `GOWORK=off GOPROXY=off go build` to a temporary binary.
- Race tests for `internal/framework/pipeline`, `internal/framework/chunkmap`,
`internal/core/source`, `internal/cli`, and
`internal/modules/dnd/extract/scenedescriptions`.
- Executable `version`, offline pipeline validation of both maintained D&D
examples, and native spell prompt-requirements inspection.
- `git diff --check`, this document's local link destinations, and the affected
configuration-reference anchors.
The scene-cache regression covers both repartitioning directions, bypass
controls, current IDs, actual reuse without reassessment, and unusable hits.
The fallback regression exercises a real typed spell pipeline with a fake long
provider failure; focused checks retain full causes and module diagnostics.
Source/cache/capture regressions cover nonmonotonic unit order, concurrent hits,
and exact sensitivity routing without native snapshot mutation. No production
inference, new permanent validation gate, or performance guarantee was added.