Epic: Make time-to-answer a product-level performance contract

[Joncallim]

Goal

Make “total speed” a product property, not an impression.

DockerMap should publish the first useful Docker answer as soon as authoritative Docker evidence exists, keep optional/enrichment work off that critical path, avoid refetch/recompute work when only unrelated evidence changes, and mechanically prevent meaningful regressions.

Product outcome

For the target single-host Compose operator, DockerMap should feel immediate in four different senses:

• startup speed — the UI/API becomes reachable before expensive collection completes;
• evidence speed — Docker facts publish independently of slower Compose/host enrichment;
• reaction speed — a daemon revision reaches the browser with minimal avoidable latency;
• cognitive speed — common questions resolve with little navigation or recomputation.

This epic is about measured time-to-answer, not synthetic benchmark chasing.

Current-main findings motivating this epic

• Docker/host provider collection is already well decoupled and bounded.
• Compose runtime correlation still runs inside the five-second Docker snapshot publication budget.
• The daemon waits for the initial refresh_cache() before binding its HTTP listener.
• Independent Docker inventory reads are currently sequential.
• Browser model refreshes refetch Snapshot + Runtime Map + Findings together when the broad model revision changes, even when only one facet changed.
• Node SSE polls daemon health on a fixed interval, adding avoidable revision-notification latency and per-stream daemon work.
• Home still renders the legacy force-layout Service Map; its layout is expensive relative to a summary surface and can rerun on unrelated model revisions.
• Atlas has controlled performance evidence, but DockerMap as a whole has no end-to-end performance authority.

Sequence

Blocked only by the small authority cleanup in #332 for trustworthy baselines/docs.

Recommended child order:

1. establish the end-to-end performance harness and baseline;
2. make first Docker publication independent and fast;
3. add revision-scoped selective refresh / lower notification latency;
4. remove avoidable frontend work and bundle cost;
5. rerun certification and freeze budgets.

Children may overlap only where they do not invalidate the controlled baseline environment.

Non-negotiable constraints

• Do not weaken modelRevision/source/provenance coherence for speed.
• Do not make stale provider evidence look fresh.
• No raw Docker socket fallback.
• No new runtime telemetry solely to benchmark production users.
• Optional provider/Compose work may enrich the current model later; it may not delay publication of already-authoritative Docker facts.
• Performance tests must use controlled fixtures/runners; ordinary CI wall-clock timing is not a reliable gate.
• No feature removal merely to improve a number without a product decision.

Acceptance criteria

• A controlled performance contract covers process start → listener, listener → first useful Docker publication, Docker collection, daemon publication → browser awareness, browser update → Review render, buildModel, Findings derivation, Home render, and command/search response.
• First Docker publication no longer waits for Compose filesystem projection.
• Daemon HTTP availability no longer waits for the first collection pass.
• Independent Docker inventory reads are concurrent or there is measured evidence that concurrency is unsafe/not useful.
• Browser refresh work is scoped to changed semantic facets while preserving atomic/coherent presentation.
• Per-client SSE streams do not each create unnecessary daemon polling work; revision notification latency is measured and bounded.
• Provider-only changes do not cause avoidable legacy topology-layout recomputation.
• Production frontend has a reviewed bundle/code-loading budget.
• 25/100/250-container reference fixtures remain responsive and truthful.
• Full security, contract, live-Docker and production-image gates remain green.

Non-goals

• Multi-host.
• Monitoring-grade CPU/memory metrics.
• Kubernetes.
• Replacing the Atlas/Service Map product decision.
• Relaxing security/redaction/coherence boundaries.
• Premature micro-optimization of rule loops without measured evidence.

Closure evidence

Record:

• baseline and final controlled measurements;
• exact environment/source revisions;
• architecture changes that moved work off the critical path;
• resource/revision refresh matrix;
• bundle evidence;
• 25/100/250 fixture results;
• live-host qualitative “time to first useful answer” exercise;
• exact tested SHA and full gates.

Risk: MEDIUM · read_only_product_behavior: true · security_sensitive: true (transport/coherence boundaries) · data_migration: false · routing_mode: stable

[Joncallim]

Filed child sequence

This epic is intentionally limited to four implementation slices:

1. #333 child: Establish end-to-end time-to-answer baselines and regression gates #335 — establish end-to-end time-to-answer baselines and regression gates.
2. #333 child: Make the first Docker answer independent of Compose and cold-start work #336 — make the first Docker answer independent of Compose and cold-start work.
3. #333 child: Add revision-scoped selective refresh and remove avoidable SSE polling latency #337 — add revision-scoped selective refresh and remove avoidable SSE polling latency.
4. #333 child: Remove avoidable frontend work from Home, topology and route loading #338 — remove avoidable frontend work from Home, topology and route loading.

Shared authority cleanup: #332.

Recommended execution: #332 → #335 → (#336 and architecture for #337) → #337/#338 → final #333 certification.

Do not open micro-optimization children unless #335 demonstrates a material bottleneck not owned by one of the four slices.

[Joncallim]

Architecture hand-off — 29 September 2026

Scope: programme-level architecture and acceptance contract for #333. This is a reviewed design hand-off, not implementation evidence, benchmark promotion, worker dispatch, merge approval or an instruction to close the issue.

1. Verified basis and ownership

Remote main inspected at cd70425fe777b02077b32b65d0ccf8041c1838b8. #335 supplies Baseline 4; #348 supplies the runnable promotion comparator. Draft #347 implements #336 but remains parked with a failed promotion. The separate, unpushed #337 work is reported at 9e122b740e578ae156c95865ad2cb88072bea262 in Joncallim/hermes-bridge#11–#13; that local source was not directly accessible in this review. Reconcile its actual owner, full HEAD and working tree before any implementation. Do not duplicate or overwrite it.

The remaining programme has three implementation owners, not a new performance framework:

Owner	Architectural responsibility	Must not own
#336	Listener readiness; bounded Docker observation; coherent asynchronous Compose enrichment	Browser refresh policy or benchmark waivers
#337	Publication/facet attestation; daemon→Node notification; atomic browser acceptance	A competing model authority or synthetic performance path
#338	Route loading; topology geometry invalidation; Home compute/download cost	Atlas default cutover or changing Findings truth

#340 owns Home's product composition; #338 owns its performance mechanics. Assign one editor for shared Home/AppShell/model files. Preserve the existing stack until its dependencies are reconciled; do not rebase or cherry-pick another worker's unpublished work speculatively.

2. Architecture to preserve

Use this pipeline as the stage and ownership map:

listener available → bounded Docker observation → atomic authoritative publication → optional matching Compose/provider enrichment → publication notification → Node authoritative observation → browser coherent acceptance → visible Review answer.

A notification is a hint to observe committed authority, never permission to combine arbitrary resources. modelRevision remains the combined-publication authority. Facets only prove that specific semantic content can be reused. Health, evidence coverage and Findings must continue to describe the same accepted source/publication; old evidence cannot become fresh merely because its containing page refreshed.

Define the useful-answer population explicitly: a valid empty Docker inventory can be an authoritative answer; mock data, an initializing response, a TCP connection, or a spinner cannot count as first Docker answer. Compose completion is separately measured and cannot gate Docker-only usefulness.

3. Measurement decision — retain the current FAILs

Baseline 4 remains immutable, including methodology dockermap-v1/time-to-answer-methodology-8, its fixture matrix, fixed conditioning, environment compatibility fields and max(baseline × 1.25, baseline + 2 ms) rule. Source/harness/binary digests remain provenance, not fields that must match between different candidate code revisions.

Two changes require explicit measurement-authority treatment, not favourable reinterpretation:

1. #333 child: Make the first Docker answer independent of Compose and cold-start work #336 moves a stage boundary. Record process-start→first-authoritative-model directly for each observation using paired endpoints. A sum of independently summarised stage p95s or medians is not the p95 of the end-to-end operation. Historical stage failures stay visible. Any replacement promotion contract needs a separately reviewed version and fresh baseline/candidate captures under that same protocol; it cannot retrospectively make #336: first Docker answer independent of Compose and cold-start work (parked — Baseline-4 promotion FAILED) #347 pass. Its browser/query regressions need separate investigation even if total startup improves.
2. #333 child: Add revision-scoped selective refresh and remove avoidable SSE polling latency #337 changes the notification mechanism. Measure the actual product watch/Node observer, not the old synthetic two-second poll. Preserve the old phase-response evidence with its original meaning. A changed ssePollIntervalMs is incompatible under the existing contract; do not delete that check. Version the new protocol and state exactly which comparisons are valid. Protocol-specific evidence is not automatically a Baseline-4 promotion.

Every stage sample must identify its causal publication where the claim requires it. Run the negative control: break/delay the relevant product path and require the measurement to fail/increase, rather than succeed through a recovery poll or an earlier publication. Keep the existing Stage-6/7 seam-control limitation disclosed until it has actually been repaired and tested.

4. Review passes and resulting safeguards

• Authority pass: rejected a separate fast-but-unattested browser model. Commit only a coherent accepted envelope; retain old bytes with their real origin on failure.
• Concurrency/failure pass: asynchronous enrichment and repeated publications can cause starvation or refresh storms. Require bounded single-flight collection, latest-state notification coalescing, stale-request fencing and bounded retries without deleting correctness checks.
• Measurement challenge: rejected sums of summary statistics, changing pinned fields to force compatibility, and a harness that times scaffolding rather than the product.
• Integration pass: cached geometry and answer-index work must be tested after #334 child: Make Home a Review surface with separate Health, Review and Evidence Coverage #340–#334 child: Add Review dispositions without changing Finding truth #343 integrate, not only on a pre-Review frontend. New coverage/context/disposition semantics must have explicit invalidation dependencies.

5. Required delivery and exit evidence

Implement in bounded, independently reviewable slices: reconcile current #336/#337 branches and blockers; repair proof/gates; land the existing children in a dependency-safe order; then certify the integrated product. Architecture-only work may proceed in parallel, but controlled captures must have exclusive runner ownership.

The closing evidence pack must contain exact source/harness/binary identities; environment and fixture manifests; raw samples plus deterministic summaries; resource-refresh and cache-invalidation matrices; production initial/route bundle inventories; 25/100/250 results; failure and reconnect scenarios; and a real-host exercise from launch to a useful inspection answer. Record all regressions and all commands not run.

Use npm run check, affected API/contracts/Rust/performance suites, npm run test:e2e, npm run test:live-docker, npm run build:deploy, and the repository's production-image gate at the final tested SHA. A successful earlier SHA or a partial command battery is not interchangeable evidence. Rollback must restore a previously coherent implementation, not bypass source, redaction, auth or comparison validation.

Current disposition: keep #333 open. This review specifies the architecture and proof obligations; it did not execute the product or rerun the controlled benchmark.

Sources: Baseline-4 authority, notification comparison authority, parked #347, current browser acceptance, agent/evidence rules.

[Joncallim]

Architecture amendment — second optimisation pass, 29 September 2026

This amends the first hand-off. The replacement clauses below take precedence; unchanged security, measurement and closure requirements remain. Remote main is still cd70425fe777b02077b32b65d0ccf8041c1838b8; #347 remains an unmerged draft at 09c56153b9e61a04fa579f05e4c87f23f383ccc3. This is architecture maintenance, not execution approval.

Preserve availability while enforcing coherence

Do not turn the shared accepted envelope into an all-or-nothing dependency on every optional resource. Preserve the current two-resource base contract: matching Snapshot + Runtime Map can advance without Findings. Represent the Review overlay explicitly as pending, ready or unavailable; attach it only when its source and facet/publication proofs authorize that base. A missing overlay is not zero findings. Old Findings must never decorate a newer base as current; any retained Review must be a separately labelled previous observation.

Measure first useful Docker answer separately from first usable Review answer. Context, search indexing, optional enrichment or an unavailable Findings endpoint must not delay the former. Conversely, a base-only render cannot satisfy a benchmark claiming Review readiness. This resolves a possible availability regression introduced by reading the first hand-offs' coherence language too broadly.

Reduce invalidation, not safety checks

Require one integration matrix mapping each published semantic change to resource fetches, model construction, Review projection, search partitions and geometry work. Background Compose task activity alone is not a semantic change; #336 owns finite evidence validity and #337 owns its attestation. Presentation/preference changes must not trigger Docker fetches. Unchanged semantic content must not receive a new facet token merely because an envelope was restamped.

Keep one owner for shared acceptance and Home files. Do not introduce a general cache/event framework or additional endpoints simply to satisfy the matrix.

Make verification economical without weakening it

Run deterministic race, failure and work-count tests before expensive controlled captures. A final exact-SHA evidence pack may serve several issues when it really covers their affected paths, environment and configuration; cross-reference it rather than repeating identical full batteries twelve times. A subsequent code or relevant configuration change invalidates the affected evidence and requires rerunning it.

Baseline 4 and its failed promotions remain unchanged. New paired startup endpoints or a real notification-path methodology require a separately reviewed protocol and compatible baseline/candidate captures. Never sum independently calculated percentiles, remove pinned compatibility fields, or classify recovery-poll success as notification-path success. Keep historical stage failures visible alongside new evidence.

Added acceptance cases

Prove that a permanently failing Findings request does not freeze a successfully refreshing base; a late old overlay cannot attach; unchanged Compose revalidation does not cause publication/Review flicker; and a preference edit causes zero Docker requests and zero unchanged layout calls. Record base-ready and Review-ready events separately and make each measurement fail when its actual product path is blocked.

Source: current optional Findings/base acceptance. No product tests or benchmark captures were run in this amendment pass.