123 lines
6.4 KiB
Markdown
123 lines
6.4 KiB
Markdown
# Computational Efficiency Roadmap
|
||
|
||
**Status:** All five target components implemented. The
|
||
[implementation record](implementation.md) owns completed stages and performance
|
||
results; the [remediation record](remediation.md) owns review findings and their
|
||
completion status.
|
||
|
||
## Objective And Ownership
|
||
|
||
Reduce the time, allocations, retained memory, and repeated I/O of routine
|
||
release operations. Improvements belong behind the existing `releasekit` and
|
||
`buildinfo` facades and follow the [architecture policy](../policy/architecture.md)
|
||
and [routine-release priorities](../adr/0002-routine-releases.md).
|
||
|
||
This document owns the desired target state and its rationale. The
|
||
[implementation plan](implementation.md) owns stages, tasks, validation, and
|
||
implementation status. The [internal inventory](../internal/overview.md) and
|
||
focused internal documents own implemented mechanics; Go declarations and
|
||
GoDoc own public contracts.
|
||
|
||
## Review Evidence
|
||
|
||
The computational efficiency review examined commit `db9e24f` on 2026-10-09.
|
||
Temporary offline probes produced these local measurements:
|
||
|
||
| Probe | Result |
|
||
| --- | --- |
|
||
| Read 1,000 unique committed Go blobs totaling 59,670 bytes through the existing path | 1.83–2.00 seconds across three runs. |
|
||
| Read and verify the same blobs through one Git batch command | 48–59 milliseconds across three runs. |
|
||
| Read a cached 1 MiB blob | One allocation of 1 MiB per read. |
|
||
| Resolve runtime version through the Go build metadata fallback in a test executable | Approximately 2 microseconds, 1,184 allocated bytes, and seven allocations per call. |
|
||
| Resolve an injected runtime version | Zero allocations. |
|
||
|
||
Blob timings cover content access, with tree metadata discovery measured
|
||
separately. They exclude Go tests, compilation, formatting, and Markdown parsing.
|
||
The fixture contained small, loose Git objects. These are component measurements
|
||
on one machine; overall release gains depend on consumer workloads. The probes
|
||
were temporary and left the repository unchanged.
|
||
|
||
Static review also identified repeated artifact hashing and unconditional Go
|
||
output copying. The [implementation record](implementation.md) contains their
|
||
baseline and completed-implementation measurements.
|
||
|
||
## Desired Target State
|
||
|
||
### Git Content Access
|
||
|
||
Selected file checks share an operation-scoped Git content reader. Requests
|
||
remain lazy, use committed object IDs, and consume responses incrementally.
|
||
Subprocess startup is amortized across the operation. Metadata-only checks
|
||
continue to use the captured tree without starting a content reader.
|
||
|
||
The reader preserves offline object access, cancellation, contextual inspection
|
||
errors, and explicit process cleanup. Each validation operation owns its reader
|
||
and reusable data independently.
|
||
|
||
### Validation Memory And Reuse
|
||
|
||
One-use regular-file bytes belong to their immediate consumer and are released
|
||
from retained references after inspection. Repeated work reuses immutable parsed
|
||
or compact results keyed by object ID within the relevant check. Reusable
|
||
symlink targets belong to the candidate tree. Link checks apply shared document
|
||
data in each source path's own context, preserving findings, source locations,
|
||
and relative destinations.
|
||
|
||
This replaces retention of every inspected raw blob with data that supports
|
||
actual repeated work. Explicit repeated raw reads may reread an object through
|
||
the batch reader. The same bytes can be interpreted separately by different
|
||
checks; reuse within one interpretation preserves object-ID deduplication.
|
||
|
||
### Artifact Verification
|
||
|
||
Delivery declarations reuse recorded digests and collect file metadata. One
|
||
preflight verification checks current local bytes before hosted requests. This
|
||
combines adjacent declaration-time and asset-verification hash passes for both
|
||
managed and prebuilt delivery.
|
||
|
||
Build-result hashing and upload preflight retain their separate responsibilities.
|
||
Prebuilt artifacts remain caller-owned. Exact remote content comparison,
|
||
targeted reconciliation, additive retries, and partial-delivery outcomes retain
|
||
their existing semantics under the [Gitea contract](../integrations/gitea.md).
|
||
|
||
### Go Command Output
|
||
|
||
Status-consuming commands return status and useful failure diagnostics.
|
||
Output-consuming commands receive ownership of completed captured bytes without
|
||
an additional full-buffer copy. Forwarded output, synchronization, command
|
||
environments, cancellation, and failure causes retain their existing behavior.
|
||
|
||
Complete diagnostic capture remains in memory for this implementation. Its
|
||
remaining cost is measured with large output. Disk-backed capture is a possible
|
||
follow-up when its benefit justifies additional filesystem and lifecycle work.
|
||
|
||
### Runtime Version Lookup
|
||
|
||
The runtime implementation resolves its immutable build-metadata fallback once
|
||
and shares that result safely across calls. Linker injection retains precedence
|
||
and its inexpensive path. Main-module version selection and the development
|
||
fallback retain the [runtime facade's semantics](../consumers/runtime-version.md).
|
||
The runtime dependency graph remains small and independent of orchestration.
|
||
|
||
## Priorities And Evaluation
|
||
|
||
| Priority | Improvement | Expected benefit |
|
||
| --- | --- | --- |
|
||
| High | Batch selected Git blob reads | Amortize subprocess startup and object access across many files. |
|
||
| High | Clarify file-content ownership and selective reuse | Reduce copies and memory retained across validation checks. |
|
||
| Medium | Consolidate artifact hashing | Reduce repeated full-file reads and SHA-256 calculations. |
|
||
| Lower | Avoid unnecessary Go-output copies | Reduce allocation and peak memory for commands with large diagnostics. |
|
||
| Low | Cache runtime version fallback | Reduce repeated metadata parsing when consumers call the accessor frequently. |
|
||
|
||
Evaluate component and complete-workflow gains with offline local fixtures,
|
||
including unique and repeated object IDs, packed objects, large files, fresh
|
||
delivery, and retries. Record workload descriptions, allocations, elapsed time,
|
||
and retained-memory observations. Timings inform implementation and remain
|
||
measurements specific to the workload and machine.
|
||
|
||
Preserve the efficient foundations already present: batched tree metadata,
|
||
parsed Markdown reuse, streamed artifact I/O, one selected Go test suite, native
|
||
artifact reuse for version smoke checks, and source-only delivery without
|
||
compilation. Publication guards and exact content comparisons retain their
|
||
existing responsibilities throughout this work.
|