semantics(connection): close() on one wrapper disconnects siblings sharing a non-persistent DSN-cached entry

[satwareAG-ironMike]

Summary

Pre-existing semantic quirk surfaced during the #576 review (PR #577), explicitly deferred there as out of scope. Memory-safe since #577; this is about close() semantics for shared non-persistent connections.

fbird_connect() deduplicates connections per DSN via the EG(regular_list) hash cache (_php_fbird_connect_link, reuse path). Two Firebird\Connection objects created for the same DSN therefore wrap one resource entry:

$a = fbird_connect($dsn);
$b = $driver->connect($dsn);   // same underlying entry (cache reuse)
$a->close();                    // fires the link dtor -> server link CLOSED
$b->isConnected();               // false - silently disconnected

Old behavior had the same observable effect (non-plink branch always zend_list_close), so nothing regressed in #577 - but with owned refs we now have the machinery to define better semantics.

Questions to answer

1. Should closing one of several wrappers sharing an entry disconnect the others? (Current + legacy answer: yes.)
2. Reference semantics of PDO_Firebird / other PHP DB exts: most treat each connection handle as independent (no DSN dedup for non-persistent links).
3. Options:
   • a) Keep current behavior, document it ("close() closes the shared server link")
   • b) Per-wrapper logical handles over one physical link (refcounted close: last wrapper closes) - larger change
   • c) Disable non-persistent DSN dedup (each connect = own entry) - changes perf characteristics, aligns with other extensions

Related

• fix(#576): Connection owns its resource ref - 3-site UAF/undercount cluster #577 / segfault: Firebird\Connection GC destruction use-after-free (doctrine-downstream red on main since 2026-08-09, crash from e260fb7/v13.2.7) #576 - ownership fix (this quirk became visible/reachable in review)
• fix(ci): fix release-linux.yml workflow file parse error #202 - pre-clear dance for default_link on persistent links (plinks already behave differently: rc>1 close is a no-op)
• flaky(test): testSetIsolationLevelSerializable 'lock conflict on no wait transaction' (RDB$RELATION_FIELDS) - research-first #578 - DDL-lock flake research (lingering shared links also play into lock lifetime)

Acceptance criteria

1. Documented decision (docs note at minimum)
2. If changed: regression phpt covering two-object share + close order permutations

[satwareAG-ironMike]

Reconciliation vs b05776a (#576): not addressed - still valid. The rework changed Connection-wrapper resource ownership, not the DSN-cache sharing semantics. This remains a design decision (shared non-persistent entry: close-one = disconnect-all vs refcounted siblings), triaged behind the correctness cluster (#580/#582) since it is [refactor]-scoped and has no crash symptom.