Search Semantics Matrix

Phase 1 establishes the stable search contract shared by:

This phase does not change the underlying architecture described in Areas Where the Go Port Exposes Different or Additional Behavior.

Compatibility Decision

The stable parity contract for the Go port is explicit Go return semantics, not runtime-configurable throw/null mode.

Retained compatibility flags:

Phase 1 replacement contract:

these flags remain available as compatibility metadata for ports coming from SikuliX
they do not alter Go method signatures
they do not suppress ErrFindFailed
they do not suppress ErrTimeout
screen-backed gRPC calls map to the same contract rather than maintaining a separate miss/wait policy

Operation	Image-backed `pkg/sikuli` behavior	Screen-backed gRPC behavior
`find`	returns `Match, nil` on hit; returns `ErrFindFailed` on miss	returns `FindResponse` on hit; maps miss to `codes.NotFound`
`exists`	returns `(Match{}, false, nil)` on miss; returns `(Match, true, nil)` on hit	returns `ExistsOnScreenResponse{exists:false}` on miss; returns `exists:true` with `match` on hit
`has`	returns `bool, error`; miss is `false, nil`	composed from `exists` semantics
`wait`	polls until hit; returns `ErrTimeout` when the wait budget is exhausted	polls until hit; maps timeout to `codes.DeadlineExceeded`
`waitVanish`	returns `true, nil` once absent; returns `false, nil` on timeout	not yet exposed as a dedicated RPC in Phase 1

Phase 1 moves the search source of truth into:

Shared helpers:

These helpers define:

Image-backed coverage:

Screen-backed coverage:

Phase 1 intentionally does not do the following:

Those changes belong to later phases in: