555 lines
30 KiB
Markdown
555 lines
30 KiB
Markdown
# 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. This document records findings, not implemented fixes.
|
||
|
||
## 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
|
||
|
||
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
|
||
|
||
Priority: P3. Relevant stages: 8, 24, 35, and 44.
|
||
|
||
### Evidence And Impact
|
||
|
||
[`contracts/errors.go`](../../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
|
||
|
||
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
|
||
|
||
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
|
||
|
||
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
|
||
|
||
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.
|