# 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.