docs(decorator): document last-writer-wins for register_openapi_metadata

[yeongseon]

Summary

• Resolves fix(registry): register_openapi_metadata silently overwrites on duplicate method::path #397 as by design after Oracle cross-validation: a method+path pair is a single OpenAPI operation, so re-registering it is an intentional last-writer-wins replace — not a collision between two distinct operations.
• This semantic powers the documented scan-then-enrich pattern (examples/partner_import_bridge): scan_endpoint_metadata seeds a minimal bridge/validation entry, then an explicit register_openapi_metadata call overrides it with richer, human-authored metadata. Treating the second call as an error/warning would break this first-class workflow.
• Bridge-seeded and user-programmatic entries are structurally identical (same method::path key and programmatic.* _function_id), so there is no non-fragile way to distinguish "legitimate override" from "accidental overwrite" — and per the OpenAPI data model there is nothing to distinguish, since one operation can exist per method+path.

Changes

• Document the last-writer-wins contract in the register_openapi_metadata docstring.
• Add a debug-level log on replace so the override stays traceable without noise.
• Add a regression test locking the behavior (last entry wins, single surviving entry, no spurious DUPLICATE_OPERATION warning).

Why not the originally-proposed fix

The issue proposed recording collisions via add_duplicate_operation. That is incompatible with #393 (which recomputes duplicate_operations purely from registry state each generation — the overwritten entry leaves no trace to re-derive) and would break the bridge-then-enrich example. See issue thread.

Validation

• make check-all green (tests + lint + typecheck + security).

Closes #397