[FEATURE] Report completed Cargo preparation work while it runs #187

Open
opened 2026-10-24 08:30:55 +02:00 by erikinkinen · 0 comments
Owner

Problem and motivation

Cargo preparation can complete many owned Git operations and source copies before the gateway returns its final JSON. Those operations retain private evidence, but an enclosing command observer receives no indication that preparation is advancing. Long offline builds need visible completed work without synthetic keepalive output or relaxed deadlines.

Proposed behavior and scope

Add an explicitly selected preparation progress stream on stderr. Keep stdout as the original final JSON. A concrete reporter should emit fixed ASCII records after completed native queries, checked source copies, persistence and source registration. Distinguish a sealed copy from a synchronized snapshot. Library callers remain silent unless they supply the reporter; the CLI must select a finite output byte allowance explicitly.

Use the existing live-output route so enclosing owners receive the actual bytes. Do not add a timer, file-tail observer, process-discovery route or source replay. Profiler measurements remain separate telemetry.

Authority, security and reliability

The caller supplies the original output recipient and its byte budget. Report only after the producing operation, required input checks and native cleanup succeed. Use closed stage names and cumulative scalar counts, without provider text, paths, commands or process identities. A record attests only its stated local milestone, never complete source acceptance or cleanup authority.

Retain the first write or flush failure, handle positively written prefixes once and stop later ordinary emission. Do not report success from failure or cleanup paths, replace an earlier source error, or replay work to obtain a missing message. Preserve all original total and quiet deadlines, cancellation, stream limits and owner retirement.

Acceptance criteria

  • Thread one explicitly selected reporter through actual gateway preparation and its owned source operations; keep library defaults silent and stdout JSON unchanged.
  • Emit each milestone only after its actual completion checks, with sealed and persisted stages kept distinct.
  • Preserve first failures, partial writes, exact output accounting and native custody on sink refusal or cancellation.
  • Show completed-work bytes reach both existing enclosing recipients; profiler activity, elapsed time and repeated verification must not count as progress.
  • Retain the original hard deadline and quiet-expiry behavior when no further work completes; cover malformed records and exhausted output allowances.
  • Update the build-system contract and technical manual, and keep the full selected helper closure bound to the changed source.

Alternatives and tradeoffs

Increasing quiet time hides the missing output and weakens stall detection. A heartbeat or watched receipt file says little about completed work and introduces another observer. Completed-work reporting uses the existing owned streams, but its bytes must be included in the caller's original resource plan.

Tracking and rollout

Extend the Integration review and build/profiling work. The snapshot profiler keeps its separate measurement semantics. Adopt progress only through an explicit caller selection with a complete source and output budget.

## Problem and motivation Cargo preparation can complete many owned Git operations and source copies before the gateway returns its final JSON. Those operations retain private evidence, but an enclosing command observer receives no indication that preparation is advancing. Long offline builds need visible completed work without synthetic keepalive output or relaxed deadlines. ## Proposed behavior and scope Add an explicitly selected preparation progress stream on stderr. Keep stdout as the original final JSON. A concrete reporter should emit fixed ASCII records after completed native queries, checked source copies, persistence and source registration. Distinguish a sealed copy from a synchronized snapshot. Library callers remain silent unless they supply the reporter; the CLI must select a finite output byte allowance explicitly. Use the existing live-output route so enclosing owners receive the actual bytes. Do not add a timer, file-tail observer, process-discovery route or source replay. Profiler measurements remain separate telemetry. ## Authority, security and reliability The caller supplies the original output recipient and its byte budget. Report only after the producing operation, required input checks and native cleanup succeed. Use closed stage names and cumulative scalar counts, without provider text, paths, commands or process identities. A record attests only its stated local milestone, never complete source acceptance or cleanup authority. Retain the first write or flush failure, handle positively written prefixes once and stop later ordinary emission. Do not report success from failure or cleanup paths, replace an earlier source error, or replay work to obtain a missing message. Preserve all original total and quiet deadlines, cancellation, stream limits and owner retirement. ## Acceptance criteria - [ ] Thread one explicitly selected reporter through actual gateway preparation and its owned source operations; keep library defaults silent and stdout JSON unchanged. - [ ] Emit each milestone only after its actual completion checks, with sealed and persisted stages kept distinct. - [ ] Preserve first failures, partial writes, exact output accounting and native custody on sink refusal or cancellation. - [ ] Show completed-work bytes reach both existing enclosing recipients; profiler activity, elapsed time and repeated verification must not count as progress. - [ ] Retain the original hard deadline and quiet-expiry behavior when no further work completes; cover malformed records and exhausted output allowances. - [ ] Update the build-system contract and technical manual, and keep the full selected helper closure bound to the changed source. ## Alternatives and tradeoffs Increasing quiet time hides the missing output and weakens stall detection. A heartbeat or watched receipt file says little about completed work and introduces another observer. Completed-work reporting uses the existing owned streams, but its bytes must be included in the caller's original resource plan. ## Tracking and rollout Extend the [Integration review](https://git.erikinkinen.fi/erix/integration/pulls/12) and [build/profiling work](https://git.erikinkinen.fi/erix/integration/issues/3). The [snapshot profiler](https://git.erikinkinen.fi/erix/integration/src/branch/feature/posix-compat/docs/source-snapshot-performance.md) keeps its separate measurement semantics. Adopt progress only through an explicit caller selection with a complete source and output budget.
erikinkinen added this to the Alpha 1 milestone 2026-10-30 09:34:21 +01:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
erix/integration#187
No description provided.