#334 child: Build a local answer index and make deterministic Copilot Review-aware

[Joncallim]

Parent: #334. Requires the safe context and Review projection. Coordinate performance acceptance with #333.

Goal

Make the fastest common DockerMap questions answerable from Cmd-K without navigating through object pages, and ensure deterministic Copilot uses the same Review truth rather than maintaining a separate concept of attention.

Current gap

Cmd-K currently indexes navigation plus service name/role/image repository. It does not directly answer common lookup jobs such as:

• who owns host port 8080?
• what uses this published path/mount source?
• which service uses this named volume/network/image?
• show offline services;
• show drift findings;
• what currently needs review?

Copilot can answer some port/service questions but does not consume coherent Findings/Review state.

Answer index

Build one deterministic in-memory index from already-public safe model/Review fields only.

Index classes should include where safely available:

• services/runtime subjects;
• published/exposed ports with correct side semantics;
• published mount/path values already allowed by the browser model;
• named volumes;
• networks;
• images;
• finding/review titles/categories/rule labels and safely resolved subjects;
• navigation/actions.

Do not index hidden evidence IDs, private Compose binding IDs, raw provider material, secret-redacted values as if they were recoverable, or anything unavailable to the current authenticated browser model.

Support plain text plus a very small closed qualifier set if useful, for example:

• port:8080
• path:/volume1
• state:offline
• finding:drift

Do not build an open-ended query language.

Context-preserving results

A result is not just a route. It should retain the reason it matched and take the user to the relevant subject/lens/tab/context where possible.

Examples:

• 8080 → service → Network/Access context;
• path → service → Storage/mount context;
• finding → exact Review thread / affected subject;
• image → image detail and consuming services.

Copilot

Extend deterministic Copilot inputs with the coherent Review/Findings projection.

Questions such as:

• “what needs review?”
• “what are the warnings?”
• “why is this being flagged?”

must use the same priority/context/limits as Review. Copilot must not invent a second ranking or stronger causal language.

Performance

• Precompute/recompute the index only when its relevant semantic revisions change.
• Query filtering should remain comfortably sub-frame at the 250-container fixture; exact promotion gate comes from Epic: Make time-to-answer a product-level performance contract #333 baseline.
• Opening Cmd-K must not block on network calls.

Acceptance criteria

Task/browser tests cover:

• “8080” finds correct published-side owners;
• exposed-only ports are not called published;
• representative safe mount/path lookup;
• named volume/network/image lookup;
• state:offline;
• finding/review lookup and exact context handoff;
• collision/ambiguous identities fail closed;
• Review-aware Copilot answer is identical in truth/order to the Review projection.

No result may reveal data not already public to that browser session.

Non-goals

• No external search service.
• No embeddings/vector DB.
• No LLM.
• No fuzzy identity correlation.
• No filesystem scan from the browser.

Risk: MEDIUM · read_only_product_behavior: true · security_sensitive: true (search can accidentally widen disclosure) · data_migration: false · routing_mode: stable

[Joncallim]

Architecture hand-off — 29 September 2026

Basis: main cd70425fe777b02077b32b65d0ccf8041c1838b8; inspected model.ts, copilot.ts, accepted-model source gating and Finding presentation. The existing Copilot is deterministic and must remain so. This is an implementation design, not a claim that query latency has been measured.

1. One local index over approved public facts

Create one pure AnswerIndex built from the accepted public model, safe #339 contexts and #341 Review projection. Do not crawl raw provider metadata, daemon objects, configuration files, environment variables, logs, private binding IDs or unapproved paths. Opening Cmd-K or asking Copilot a question performs no new network/collector request.

Use typed document kinds: service, published-port fact, public mount/path fact, network, runtime subject and Review item. Each entry carries a safe display projection, typed exact destination, evidence/coverage scope, source epoch and semantic dependency key. Private references stay out of searchable text even if they already exist as non-displayable JSON fields.

Partition the index by input semantics: Docker inventory/path/port documents; runtime/provider documents; Review/context documents. #337 facet proofs authorize reuse. History and preference changes do not rebuild Docker documents. Clear incompatible caches on source/provenance change and auth loss; a new daemon behind the same browser origin must not inherit the old daemon's index.

2. Bounded query grammar and ranking

Support a small explicit grammar first: plain literal words, exact service/entity names, port:443, state:offline, review, and approved public path text. Friendly questions map to those same typed intents. No user regex execution, shell execution, unrestricted JSON traversal or unbounded fuzzy matching.

Proposed initial limits: 256 query code points, at most eight terms and twenty visible results. Build-time document/token caps must be fixed/versioned and tested against the supported host fixture range; cap overflow produces a visible partial-index limitation rather than “nothing uses this”. Bound each indexed field and never silently reinterpret a truncated port/path as an exact fact.

Ranking is deterministic: exact structured fact/name, then prefix, then literal token match, followed by fixed kind priority and a canonical identity tie-breaker. Query normalization is for matching only; it must not alter route identity or merge case-sensitive paths. Text search resemblance never establishes a relationship between entities.

3. Ports and paths must retain their actual meaning

Service.ports is currently string[], so do not manufacture a structured host-port ownership assertion by loosely parsing display text. Reuse an existing authoritative structured publication fact where available. Otherwise add a narrow, validated public projection at the proper contract boundary, with fixtures, or explicitly label a result as a recorded port-text match rather than proven host-port use.

For a real port fact preserve host address, host port, container port and protocol where evidence supports them. Distinguish published host ports from exposed/container-only ports. Multiple matching publishers remain multiple results; a numeric match alone proves neither exclusive ownership, a listening process nor Internet reachability.

Index path/mount values only where the existing public contract already permits them. Do not reverse a private Compose binding, derive a path from a digest, reveal redacted values through tokens, or claim that a mount exists on disk merely because it was declared. Searches against unavailable/private domains return a limitation, not a fabricated negative.

4. Copilot integration

Add explicit Review intents before the current broad health-keyword branch so “what should I review first?” cannot accidentally become only a list of unhealthy services. All Review answers consume the same ordering/member facts/limits as Home and Review. A normal health query remains a health query.

Preserve the exact mode/provenance authority gate. Sample/demo answers remain labelled sample; an unresolved source produces no substantive host answer. Include the evidence limitation and a safe inspection destination. Never let grouping or a user disposition change the underlying factual explanation; an “all findings” intent can still inspect dispositioned items while the default queue explains that some are hidden.

Store a rendered answer's authorizing revision and source. If the model changes, clearly mark the answer as based on its prior observation or recompute it deliberately; do not silently leave an apparently current answer with links to replaced subjects. #339's route adapter must revalidate the exact subject and destination on activation.

5. Architecture review repairs

• Privacy leak through search: allowlist fields before tokenization. Test hidden/private sentinels across index documents, snippets, DOM, accessibility text, copied answers and URLs. Do not log or persist user queries, paths or index contents as analytics.
• False ownership: exact structured port matches and declared/observed path facts are separate result types; loose display-string matches cannot masquerade as stronger evidence.
• Split authorities: one Review projection and typed query planner feed both interfaces. Copilot must not rebuild a private priority table.
• Stale scope: logout, live↔sample transitions, daemon replacement and old asynchronous index builds cannot publish another scope's results. Fence worker results if profiling later justifies a worker; do not add one pre-emptively.
• Performance hidden by debounce: a long debounce is not a sub-frame query engine. Measure index build/update separately from warm query, first palette opening and actual result paint.

6. Test and delivery plan

Land the pure document projection and grammar with exhaustively typed results first; then update partition invalidation; then integrate Cmd-K and Copilot and remove duplicate matching logic. Keep initial work in-process and bounded. Add workers or external libraries only after a measured bottleneck justifies their lifecycle/bundle cost.

Required tests: exact/prefix/token ordering; malformed/oversized input; Unicode; same-name collisions; ambiguous runtime subjects; IPv4/IPv6 and TCP/UDP publication distinctions; multiple publishers; declared-only paths; private/redacted paths; partial index; no-results versus unknown; model change during query/click; source/auth reset; newly added Review facts; and zero network calls on palette opening/query.

On 25/100/250 fixtures report cold index build, facet-only rebuild counts, warm-query p95, first-open/result-render p95 and memory/cap behavior. Use #333's approved timing/comparison rules and #338's production bundle inventory. A missing domain must not produce a false “none” merely to make latency look good.

Run affected web/contracts/browser/accessibility tests and full/live/production gates at the final SHA. Real-host acceptance should include a port investigation, a supported public storage investigation and a Review-priority question with exact click-through. Rollback restores the old local matcher without external calls or weakening source authority.

Status: architecture reviewed; tests, real-host behavior and performance remain unexecuted here. Keep #342 open pending evidence.

Sources: current deterministic Copilot and intent ordering, current model including port strings, source acceptance.

[Joncallim]

Architecture completeness addendum — required lookup classes

The main hand-off's typed-document examples are not an exhaustive reduction of this issue's scope. The implementation must also include named volumes, images and the existing navigation/actions, as well as services, runtime subjects, ports, public paths, networks and Review items.

• Named-volume lookup uses the existing collision-safe public volume identity and an exact, evidence-backed consuming-service association. Anonymous/unresolved mounts are not relabelled as named volumes. A missing unique consumer link remains a bounded inventory result, not a guessed service route.
• Image lookup preserves the full public image reference and resolves through the existing imageByRef/collision authority. Show supported consuming services; repository-prefix text matching must not collapse distinct tags/digests into one exact identity. Route through the current typed image-detail adapter.
• Retain existing navigation commands in a fixed allowlisted partition independent of model refresh. Commands must not acquire host-write authority. Route availability and auth-dependent visibility are validated when activated.
• Include path:<literal> and finding:<literal> in the closed qualifier registry alongside port and state, with the same input bounds and privacy rules. A bare numeric query such as 8080 must prioritize exact supported host-side publication matches, not only match a service name containing those digits.

Add explicit end-to-end tasks for named volume, network, image/consumers, retained navigation, bare 8080, path: and finding:drift. The complete query-class matrix is a closure artifact. This addendum completes the scope inventory; it does not relax the main hand-off's source, collision, performance or no-network query boundaries.

[Joncallim]

Architecture amendment — second optimisation pass, 29 September 2026

Amends the first hand-off, retaining the mandatory classes/qualifiers in the completeness addendum. Basis remains main cd70425fe777b02077b32b65d0ccf8041c1838b8. This is not a reduced lookup scope.

Use the smallest bounded index

Start with exact lookup maps for typed facts plus a bounded literal/prefix scan of pre-normalized public text. Do not generate every possible prefix/substring, add fuzzy-search infrastructure or build a second model. Reuse existing collision-safe volume/network/image/service indexes and retain full exact identities separately from searchable text.

Partition static navigation, Docker/entity facts, runtime/provider facts and Review facts. Only a changed semantic dependency rebuilds its partition. A preference edit changes filtering/annotations and queue counts, not indexed fact text or Docker documents. Presentation copy changes affect only the relevant searchable presentation partition; source changes invalidate incompatible host partitions.

Bound total normalized corpus bytes, documents, field length and token work—not just query length and twenty visible results. Record concrete limits and overflow behavior with the supported fixtures before accepting the implementation. Oversized/truncated facts cannot become exact ownership assertions. Use a bounded top-result selection; report additional/partial results explicitly rather than claiming that the visible twenty are the complete population.

Make qualifier semantics exact

port: accepts a valid complete host-port value, not a partial numeric parse. Bare 8080 prioritizes exact supported host-side publication matches. Preserve protocol/address/container-side distinctions; exposed-only ports remain a different fact. Unsupported or malformed structured input must not silently fall back to a broader search while being described as exact.

For path:, preserve literal case-sensitive path identity. When offering descendant/prefix matching, require a path-component boundary: /data must not be described as the ancestor of /database. No filesystem resolution, guessed expansion, private-path recovery or lossy normalization. Plain text matching may be broader but must say why it matched rather than asserting a path relationship.

Keep named volumes, images and their supported consuming services, networks, runtime subjects, navigation/actions and finding: in the test matrix. Exact image references must not collapse different tags/digests. Missing consumer association is a bounded inventory result, not a guessed service.

Avoid stale results and displaced startup cost

Search results retain #339's expected exact subject/source and typed destination, not only /services/:name. Revalidate on activation and route completion. Unrelated provider-only changes need not break a valid result; same-name replacement must.

Opening/querying remains local. Do not hide index work in unmeasured startup or a long debounce. Measure cold build, first palette opening, warm query, result paint and partition-only updates separately. Defer heavy optional preparation only when the resulting first-open behavior still meets the reviewed product budget; keep one owner for that trade-off with #338.

Added negative checks

Exercise an oversized corpus with a tiny visible result cap, long public fields, Unicode, malformed/oversized port qualifiers, /data versus /database, case-distinct paths, partial-index no-results, exact image identity, repeated preference edits and a subject replacement between query and activation. Assert no private sentinels in tokens/snippets, no network calls, and zero unchanged fact-partition rebuilds.

Sources: existing public model and identity maps, current route shape. Performance and browser tests remain to be executed on the implementation.