Design Priority 1 semantic editor navigation MVP

[dubesinhower]

Problem

Konnect can inspect and mutate KiCad design data, but a client cannot reliably
establish and change the live editor context it is discussing with a user. It
cannot enumerate addressable schematic/PCB documents, observe the exact
selection, activate a hierarchical sheet instance, select and reveal an exact
KIID, or cross-probe a symbol to its footprint with result-derived proof.

The unsafe alternatives are guessing from open-document order, inferring live
state from saved files, or treating mouse/keyboard/window automation as the
primary interface.

This issue proposes one focused Priority 1 semantic Navigation MVP. It does not
cover Priority 2 batch inspection, arbitrary viewport control, notifications,
or structural design edits.

Foundations and related work

• fix(project): resolve schematic ownership structurally #388 and fix(schematic): preserve all hierarchical placement instances #389 establish structural project and hierarchical-instance
  identity.
• fix(ipc): bind operations to the requested board #390 binds generic IPC operations to the exact requested document.
• Draft fix(board): refuse stale locked file fallbacks #391 is an independent offline board-lock policy decision and is not a
  prerequisite for read-only navigation.
• No way to open a specific board in the PCB editor and wait for its IPC endpoint #256 covers launching a specific PCB editor and selecting the resulting IPC
  endpoint. This design may consume that capability later, but does not
  duplicate its process-launch/session-selection work.

Proposed semantic surface

Names here are provisional and require maintainer approval. The important
contract is the semantic split and evidence model.

1. get_editor_state
   • report running/addressable schematic and PCB frames;
   • report open typed documents;
   • report the active editor, document, and schematic sheet instance only
     when KiCad exposes them;
   • report the running KiCad version and a capability matrix for observation,
     selection mutation, activation, reveal/fit/center, and cross-probe.
2. get_editor_selection
   • query one explicit project/document/editor/sheet context;
   • return stable object KIIDs/UUIDs and object types with live-IPC evidence.
3. resolve_navigation_target
   • resolve one explicit project/document/editor/sheet plus KIID/UUID;
   • optionally accept a human reference such as C10 only when saved-design
     structure produces exactly one live-addressable target;
   • return structured candidates on ambiguity rather than choosing one.
4. set_editor_selection
   • semantic clear, add, and remove modes;
   • exact document/sheet/object targeting;
   • read selection back and derive success from the observed set.
5. activate_editor_target
   • activate an exact already-addressable schematic, PCB, or hierarchical
     sheet instance when the running KiCad API supports it;
   • select and reveal the exact object when supported;
   • report activation/reveal/center/fit independently so unavailable behavior
     cannot be mistaken for success.
6. cross_probe_editor_target
   • schematic symbol -> PCB footprint and reverse;
   • pin/pad/net only when one exact destination exists;
   • return both source and destination identities before any activation or
     selection side effect;
   • perform the side effect only when every required capability is present and
     verify it through readback.

An alternative with fewer public tools and tagged operations would be compatible
with these semantics. Maintainer guidance on that packaging is requested.

Target identity

Every request that can observe or change editor state should carry an explicit
context equivalent to:

{
  "project_path": "/exact/project.kicad_pro",
  "editor": "schematic | pcb",
  "document_path": "/exact/document.kicad_sch | /exact/board.kicad_pcb",
  "sheet_instance_path": ["root-kiid", "child-sheet-kiid"],
  "object": { "kiid": "stable-uuid" }
}

sheet_instance_path is required for a reused hierarchical schematic instance.
A human reference may replace kiid only at the resolver boundary; downstream
operations consume the exact resolved KIID and context. No operation may fall
back to another project, open document, sheet instance, or duplicate reference.

Evidence and success rules

• Keep saved-file structural evidence separate from live IPC editor evidence.
• Do not infer live editor state solely from files.
• Do not infer design structure solely from an editor action.
• Return stable object IDs in every result.
• Treat a successful transport call as an attempt, not success.
• After selection or activation, perform a bounded readback and derive the
  response from observed project/document/sheet/selection state.
• If KiCad 10 does not expose a stable active-frame, active-sheet, activation,
  center, fit, or reveal primitive, return an explicit unsupported capability;
  do not infer from open-document order or claim that selection implies reveal.

KiCad's typed GetOpenDocuments, GetSelection, AddToSelection,
RemoveFromSelection, and ClearSelection commands are the preferred base.
RunAction names are explicitly unstable in KiCad's protocol. No raw action
surface should be public. If one semantic activation/reveal operation cannot be
implemented otherwise, isolate its action name, gate it by KiCad version and
observed capability, and require readback before success.

Structured refusals

The public contract needs stable classifications for at least:

• ambiguous target, with candidates;
• stale target or stale editor state;
• wrong project or wrong document;
• wrong hierarchical sheet instance;
• editor unavailable or closed;
• unsupported capability/version;
• unresolved cross-probe destination; and
• post-operation readback mismatch.

Exact kind spelling should reuse Konnect's existing conventions where possible.
A former unverified success becoming a refusal should be called out in minor
version/release planning.

Acceptance

Hermetic IPC and saved-design fixtures prove this scenario:

1. observe addressable editors, capabilities, open documents, active state when
   available, and active schematic instance when available;
2. resolve C10 deterministically to one schematic KIID and instance;
3. activate that exact context or return typed unsupported;
4. select it and read back the exact project/document/sheet/KIID;
5. cross-probe to one exact PCB footprint KIID;
6. activate/select the PCB destination or return typed unsupported;
7. readback proves the destination document and selection; and
8. ambiguous, stale, closed-editor, wrong-document, wrong-sheet,
   unresolved-destination, unsupported, and readback-mismatch cases refuse.

Live KiCad checks should supplement but not replace deterministic mocks.

Decisions requested

1. Is the six-operation semantic split acceptable, or should the same contract
   be packaged into a smaller tagged-operation surface?
2. Is an explicit project_path required on every target request, or may a
   server-session project identity be accepted when it is itself observed and
   returned?
3. Should unavailable activation/reveal be a successful observation result with
   per-capability status, or a top-level structured error when the caller asked
   for that side effect?

Internal typed IPC, capability, resolver, and test foundations can proceed
without fixing these public names. PRs that expose the provisional public
surface will remain draft until these decisions are settled.

[neusse]

Maintainer decision: approve a five-operation Navigation MVP, with explicit identities and no public operation that can only pretend to act.

Public surface

Approve these operations:

1. get_editor_state
2. get_editor_selection
3. resolve_navigation_target
4. set_editor_selection
5. resolve_cross_probe_target

The first four proposed names are consistent with the repository naming rules. The cross-probe operation in #401 is read-only and performs resolution, so its public name must be resolve_cross_probe_target, not cross_probe_editor_target; a mutation-sounding name would misstate its result.

Do not publish activate_editor_target in the KiCad 10 MVP. The bundled stable protocol cannot activate/reveal/center/fit and then prove the resulting active context. get_editor_state should report those capabilities as unavailable. Preserve the semantic design and tests for a future version-gated adapter, but a public tool whose only correct KiCad 10 result is unsupported_capability is not useful API surface. No raw RunAction, mouse/keyboard, window-order, or selection-implies-reveal fallback is approved.

Identity contract

Every target-bound request must carry an explicit canonical project_path, editor kind, document identity, and schematic sheet_instance_path where applicable. A hidden server-session project default is not accepted for this MVP. get_editor_state is the enumeration exception because it discovers contexts; downstream operations must echo one exact observed context. A future opaque context token may reduce repetition only if it carries a revision, expires, and is still read back against live IPC.

Human references such as C10 are accepted only at the resolver boundary and only when they produce exactly one candidate. All downstream work consumes stable KIID/UUID identity.

Unsupported and partial behavior

Observation operations return a capability matrix/status. If a caller requests a side effect that is unavailable, return a top-level structured unsupported_capability before sending any mutation. A transport success is never result evidence. Selection mutation must read back the complete exact selection and return readback_mismatch if it differs.

Cross-probe resolution remains side-effect free. It returns both exact identities and evidence; the client may then call a supported selection operation. Pin/pad/net expansion stays out until each direction has one provable destination.

PR sequence and evidence

After #390 lands, reconstruct the navigation work from then-current main, one focused PR at a time:

• feat(navigation): observe editor capabilities #396: state/capability observation
• feat(navigation): observe exact editor selection #397: exact selection observation
• feat(navigation): resolve exact editor targets #398: exact target resolution
• feat(navigation): verify editor selection mutations #399: verified selection mutation
• feat(navigation): resolve exact cross-probe targets #401: cross-probe resolution, renamed as above and rebuilt without feat(navigation): gate editor activation capabilities #400

#400 should not enter the merge queue as a public-tool PR. Close it after any generally useful capability-model tests are either moved into the appropriate focused PR or shown to be redundant.

Each step must contain only its unique work, use current public error conventions, update generated tool counts, and pass the complete gate on its exact head. Mocks are required but do not replace a live KiCad check for behavior claimed to execute. This is additive public MCP surface and therefore belongs in minor-version release planning.

These decisions settle the three questions in the issue. I am removing needs:maintainer-decision; remaining work is implementation and evidence.

[neusse]

Implementation handoff: with exact requested-board binding and board-lock fallback safety now merged through #487 and #486, I am reconstructing the approved Navigation MVP directly from current main. I will preserve @dubesinhower authorship on each unique source commit, replace the cumulative draft PRs with focused non-stacked PRs, and land them sequentially in the approved order: #396, #397, #398, #399, then #401 renamed to resolve_cross_probe_target. #400 will not ship as a public tool; any uniquely useful capability tests will be accounted for before it is closed.

[neusse]

Terminal implementation PR: #495.

Acceptance ownership is now explicit:

1. State, addressable documents, sheet instances, version, and capability availability: feat(navigation): observe editor capabilities #488 plus test(navigation): complete unavailable capability matrix #494.
2. Exact human-reference/KIID target resolution: feat(navigation): resolve exact editor targets #492.
3. Activation/reveal/center/fit: explicitly unavailable in the KiCad 10 capability matrix; no pretend-to-act public tool, per the settled maintainer decision.
4. Exact selection observation and verified clear/add/remove readback: feat(navigation): observe exact editor selection #491 and feat(navigation): verify editor selection mutations #493.
5. Exact symbol-to-footprint and reverse cross-probe resolution: feat(navigation): resolve exact cross-probe targets #495.
6. Destination behavior: feat(navigation): resolve exact cross-probe targets #495 resolves without side effects; feat(navigation): verify editor selection mutations #493 supplies exact supported selection mutation; unsupported activation stays explicit.
7. Destination proof: feat(navigation): resolve exact cross-probe targets #495 proves the live destination document and feat(navigation): observe exact editor selection #491/feat(navigation): verify editor selection mutations #493 provide exact selection readback.
8. Required structured refusals: covered across feat(navigation): observe editor capabilities #488, feat(navigation): observe exact editor selection #491, feat(navigation): resolve exact editor targets #492, feat(navigation): verify editor selection mutations #493, and feat(navigation): resolve exact cross-probe targets #495.

#495 carries Closes #395 and is the sole terminal PR. It was reconstructed on current main without the rejected #400 activation API.

[neusse]

Completed by the sequential Navigation MVP series:

• feat(navigation): observe editor capabilities #488: typed editor/version/document/sheet/capability observation.
• feat(navigation): observe exact editor selection #491: exact selection observation with live document and sheet binding.
• feat(navigation): resolve exact editor targets #492: deterministic KIID and unique human-reference target resolution.
• feat(navigation): verify editor selection mutations #493: verified clear/add/remove selection mutation with complete readback.
• test(navigation): complete unavailable capability matrix #494: explicit unavailable activation, reveal, center, and fit capability evidence; no pretend-to-act API.
• feat(navigation): resolve exact cross-probe targets #495: exact bidirectional symbol/footprint cross-probe resolution with both live documents proven and no unsupported side effects.

PR #495 merged at cfe3427e368bc26d5c986eb0336919a8ecceabb1. All ten required hosted checks passed on its exact head, and the complete post-merge local gate passed on merged main.

The accepted five-operation MVP is complete. Activation and viewport manipulation remain explicitly unsupported for the bundled KiCad 10 protocol, and pin/pad/net cross-probe expansion remains future work rather than an unverified success claim.