macOS bring-up: the designer starts, survives adding an object, and reads correctly

[DitriXNew]

Everything found while bringing the platform up on Apple Silicon (macOS 26.6.2, arm64, Apple Clang 21, CMake + Ninja). Sections 7–9 came out of a Debug build, which is where the last three of these had been hiding. Each commit stands alone and carries its own reasoning; the issues are linked per commit.

1. The Firebird client never loads — #72

The official macOS Firebird package ships libfbclient.dylib linked against @rpath/lib/libtommath.dylib while carrying no LC_RPATH of its own, so dyld refuses: Reason: no LC_RPATH's found. ibInterfaceFirebird::Init() returns false and the startup dialog reports that the infobase could not be opened — indistinguishable from "Firebird is not installed", with the framework on disk the whole time.

Nothing set an rpath before: CMake's automatic build rpath covers linked dependencies, and fbclient is dlopen'd by name at run time. Two directories are added under APPLE, each for its own lookup — Resources/lib so the bare-name Load succeeds (without it wx logs an error alert about a library the next line loads successfully), and Resources so @rpath/lib/libtommath.dylib resolves.

2. The window is unreadable under a dark appearance — refs #74

Backgrounds are painted from a fixed light palette in code; text colour is set nowhere near them, so glyphs come from the system, and a dark appearance returns white. White on #FAF7F0: the metadata tree renders as blank rows. ibWxApp::OnInit now declares the application light through wxApp::SetAppearance, in the shared base so all four GUI apps get it.

Legibility, not dark-mode support. Real theming means a second palette and a theme-aware source for 177 hard-coded colours; that is #74, in progress on a separate branch.

3. Adding a common module killed the designer — #76

EXC_BAD_ACCESS (code=2) at the main thread's guard page — a stack overflow, three runs out of three. Twelve frames repeating:

OnSetFocus → ibView::Activate(true) → ibFrontendMainFrame::ActivateView
  → wxWidgetCocoaImpl::SetFocus() → -[NSWindow _realMakeFirstResponder:]
    → resignFirstResponder → DoNotifyFocusEvent → focus event, dispatched inline → OnSetFocus …

Activating a view moves focus; moving focus tells the window that held it; on Cocoa that telling is synchronous. Windows posts it through the message queue, which is the only reason this was never seen there.

The guard that was there could not close the loop: m_metaView != docManager->GetCurrentView() asks a question the call it guards has not yet answered — ibView::Activate records the current view after the focus moves. A re-entrancy flag, both branches, cleared by scope.

4. Every metatype the root hosts is created in a test — refs #76

The tree-mutation test spot-checked two types; the crash arrived through the same door for a third. Twenty-two kinds now go through it, filtered by ResolveChild rather than by a curated list, so the taxonomy stays in charge. The covered count is printed, not merely asserted.

This does not cover the crash itself — the recursing handler lives in designer, an add_executable, so no gtest target can link it. Making that site testable means moving the tree into a library.

5. The status bar said everything twice — #77, #78

ibDocBottomStatusBar put its text in a wxStaticText child at wxPoint(5, 5) while the bar painted the same field underneath. DoUpdateStatusText overrides when the text changes, not how it is drawn.

The child was not gratuitous — wxStatusBarGeneric::DrawFieldText never calls SetTextForeground, so the field is drawn black whatever SetForegroundColour says. Setting the DC's colour is the whole of what the child was for, and DrawFieldText is virtual.

A second field now carries a lamp and the endpoint when assistant access is running — the address, because when a client cannot connect that is the first question; empty when it is off, because an indicator reporting an absence in every window is noise.

⚠ OES_STATUSBAR_CUSTOM_INK == 0 has not been compiled anywhere. wx/statusbr.h picks a different wxStatusBar per platform and DrawFieldText belongs to the generic one, so the override is conditional — and the MSW branch needs an MSVC run before this is trusted there.

6. The comment markers are documented — no issue

⭐ / ⭐⭐ / ⚠ / 🛑 appear nearly six thousand times across 453 files and the rule for them was written down nowhere. Four rows in CONTRIBUTING, in the section that already says the local convention wins.

7. A Debug build never reached its window — #80

It stopped on wxBG_STYLE_TRANSPARENT can't be unset once it is set, asserted from inside ibFrontendMainFrame::Create. The process stays alive behind that dialog, so from outside it is a designer that started and then answers nothing: a refused MCP connection, no window, no error.

wxAuiMDIClientWindow → wxAuiNotebook → wxBookCtrlBase, whose HasTransparentBackground() is true; wxWindowMac::Create reads that and stamps the window transparent before our #ifdef __WXOSX__ branch runs. wx then refuses to let it go, deliberately, because wxGTK cannot honour the change.

Release behaved no differently in effect — there wxCHECK_MSG returns false in silence, so the call had been a no-op on every platform since it was written. The workspace ground comes from the paint/erase pair bound four lines below, which is why a dead line was never missed.

8. A deliberate stop was reported as a crash — #81

SIGTERM produced SIGABRT and a crash report. The main thread is in ibSessionRegistry::Stop(), the Firebird connection is going away underneath, and the registry thread's next heartbeat throws against the dying handle — "Unsuccessful execution caused by an unavailable resource". Die() then chose between its two paths on m_started alone: not started, soft-fail; started, std::terminate.

Shutdown is neither, and arrived through the same door. The hard path's stated reason — the registry was consistent, so stale state must not propagate — does not survive the transition: the process is leaving, and a stale sys_session row is exactly what the next process's eager sweep deletes, which is the idempotence the soft path already leans on.

It cost more than tidiness. Every ordinary stop left a crash report behind, the exit status was a signal death for any supervisor, and whether a run "crashed" depended on where the heartbeat fell.

9. Dropping a table onto a form killed the designer — #82

SIGSEGV at a null dereference in ibDataViewCtrl::Refresh, before the control was ever on screen. It guards four of its five area windows; m_tableAreaWin is dereferenced unconditionally in both branches.

Safe only if Refresh could not run on a half-built control — and it can: wxWindow::Create → InheritAttributes() → the virtual SetFont → ours → Refresh, all before the constructor body has run. The guards written for the optional areas are what the mandatory one needed, for a different reason than they were written for.

Conditional on the parent, which is why a table works in some places and not others: InheritAttributes only calls SetFont when the parent carries an explicitly set font.

SetFont also calls SetRowHeight(GetDefaultRowHeight()) on the same half-built object by the same path. It survives today; left alone here rather than changed on suspicion, and recorded in #82 so it is looked at deliberately.

10. Three defects in the MCP surface, found by using it — #83, #84, #85

Building a small stock configuration through the assistant interface — three catalogues, two documents, a balance register, two posting handlers — turned up three faults in the tools themselves. The behaviour is unchanged in all three; what these commits fix is the descriptions, which were wrong in ways that cost the caller real work.

config_save restructures the database — #85. Its description said the opposite in the strongest terms it had ("it does NOT become the configuration the application runs … the diskette: cheap, safe, and the thing to do before stopping work"), and the note after each save sent the caller to database_diff. Both false: SaveConfiguration goes through SaveDatabase(saveConfigFlag), and the restructure lives in that branch, which ApplyConfiguration shares as its first step. Ten CREATE TABLE and six ALTER TABLE were issued during plain saves here; config_apply {confirm: false} — the only rehearsal the engine offers — then returned an empty ledger, because there was nothing left to rehearse. The sentence taught precisely the habit that defeats the safeguard, most persuasively to someone who has just lost work to a crash. Both texts now say what the call does, and config_apply's says the rehearsal must be asked for before the save. Whether the restructure belongs behind saveConfigFlag is left open — that is a decision for whoever owns the save path.

The syntax helper carries neither the creatable types nor the platform enumerations — #83. It answers well for keywords, global functions and the Query family; Array, Structure, Container, TypeDescription, AccumulationRecordType, DocumentWriteMode return nothing. Those are the names that must be spelled exactly and cannot be inferred from an example, and the miss-message redirected to three tools that do not answer for them. Writing the posting handlers meant reading valueMap.cpp and accumulationRegisterEnum.h to recover signatures already declared, in text, beside their registrations. The miss now names the gap.

metadata_create accepts a document's ListRegisterRecord and applies nothing — #84. No refusal, no effect; the document posts to no register, and the omission surfaces later from the register. That is the one thing the server says it does not do, and it demonstrably can — an unknown property name comes back in refused, by name. My first reading, that relationships fail through this door, was wrong: ListOwner refuses a bad name with the candidate list and applies a good one. Only this property behaves this way and I could not establish why, so the description warns and the loop carries a note — no fix, because a fix would have been a guess about the property that decides whether a document posts at all.

The interface can build a configuration and then not put a row in it — #87, half fixed. Of 84 backend verbs and 15 designer ones, none creates, changes or reads business data. query_check parses a query, query_sources and query_fields describe what it may read, and nothing runs one; debug_sandbox executes code but did so "INSIDE A TRANSACTION THAT IS ALWAYS ROLLED BACK". So a configuration could be built here end to end and then only be filled by hand in the client, or by adding a data processor to the configuration for the purpose.

debug_sandbox now takes commit: true, which keeps what the code wrote instead of undoing it. Off by default, because undoing is what makes running code in somebody's live session defensible; a run that fails is rolled back whatever was asked, since keeping the half that got through is a document posted without its movements. The person at the application is told which of the two is happening, before the code runs and after it finishes — being told "nothing it writes is kept" while a commit is about to happen is the one wrong thing to say there. The flag is written last on the wire, so a runtime that predates it stops after the string and rolls back. This is the executor growing a second mode, not the read verb — reading business data still has no door of its own, and #87 stays open for it. Two descriptions also pointed at a query_run that has never existed — that half is fixed here too, since the steer they carry is right and the dangling name is read precisely where a caller is looking for something to reach for.

11. A launch from the designer produced nothing to debug — #86, #88

app_run started a process that did not exist. The command line was built from the bare target
name, and a bare name is looked up on PATH and in the working directory — it is in neither. On
macOS it is not even a plain file: what was built beside the designer is enterprise.app, with the
executable three levels inside it. The fork succeeded, the exec failed, and wxExecute still handed
back a pid, so the caller was told the application had started while nothing was running. The binary
is now resolved next to the running one, stepping out of the bundle and into the sibling's, with the
bare name kept as the fallback so an unrecognised layout behaves as before.

And once it did start, --debug still never attached — #88. Two independent faults, either
enough on its own. The designer swept the ports once and waited 1.5 s; SearchServer starts one
thread per port and numberOfConnectionAttempts is 1, so on the loopback every one of them is
finished within milliseconds of connect-refused, and the rest of that wait is spent on threads that
have already given up. The client it had just launched was not listening yet — its debug server is
created in OnInitialize, after wx is up, the database is open and the user is authenticated. The
manifest path in the same file already scans in rounds and says why; the desktop path never got it.

The debuggee, for its part, raised the flag meaning a connection was accepted whether or not one
was: Accept(true) returns null after the socket's own ten-second timeout, and the break condition
left the loop on m_waitConnection alone. CreateServer read that as its signal and asserted on
the null socket it then found — which is how a Debug client stops on a modal before its window
exists. In Release the assertion is compiled out, so --debug was accepted and no breakpoint would
ever fire, with nothing anywhere saying why. Now: scan in rounds stopping on success, keep accepting
until there is a socket, and bound the wait with a deadline that goes on without a debugger and
writes a journal line rather than asserting on a race nobody at the window can act on.

12. Four defects between a base with data in it and a report — #89, #90, #91, #92

None of these was reachable before this branch, and that is the finding rather than an excuse: with
no way to create a record through the assistant interface and debug_sandbox undoing everything it
wrote, the whole read path over live business data had never been walked. Adding commit: true and
seeding a base — three goods, a warehouse, a counterparty, a receipt, a sale — turned up four faults
in a row, each one hidden behind the one before it.

A balance filtered on a reference dimension sends a column that does not exist — #89. Firebird
refused the statement with Column unknown FLD1053. A reference is three physical fields, and the
same dimension is spread into all three in the projection, the GROUP BY and the ORDER BY of that
very statement; only the WHERE carried the bare base name. ReadFilters took GetPhysicalName()
off the leaf while ReadKeys, five lines below, asked ibRegFieldsOf for the set — so the keys were
always right and the filter never was, and the three copies of the loop in the accounting register
had it too. A primitive-typed dimension works, which is how it survived: it fails only on the
dimensions people declare. The read spec now carries whole conditions and the caller spreads each
leaf through ibRegCompositeIR, keeping L2-2 metadata-blind as its own header requires.

A catalogue or document selection never ends — #90. Three items, and while (sel.Next()) counted
past a hundred. CaptureAnchor read the row key with GetString(); that column is the queryable's
primary key, which for a catalogue is its data-reference, and a reference read as a string gives its
presentation rather than its uuid. The guid never parsed, ApplyAnchor kept answering "first row",
and every fetch was LIMIT 1 with no keyset clause. m_hasAnchor was also raised with
m_anchorSortValues left empty, so even a valid guid would have produced no predicate. It takes the
process with it: Next() runs on the parked session's thread, so a runtime that entered the loop
answered nothing afterwards and looked dead from the designer — and a sandbox run cannot be
cancelled.

Iterating documents with a tabular section segfaults — #91. ibValueSelectorRecordDataObject
derives ibValueDataObject as its second base, so the pointer needs an offset; the constructor
wrote (ibValueDataObject*)selectorObject in a file that does not include objectSelector.h, so the
type was incomplete, the cast fell back to reinterpret_cast, and no offset was applied. It compiled
silently and the first virtual call read a foreign vtable. The two constructors beside it pass their
argument with no cast at all — the cast existed only where it could not work. Latent behind #90:
with the cursor broken the owner guid was always invalid and LoadData returned before touching the
pointer.

Balances and turnovers come back as blank rows — #92. Right number of rows, every dimension empty
and every resource zero, while the movements behind them read correctly. ibRegSelectionToTable
filled each row through GetColumn(name), which reads one scalar field under the read's own output
alias — a dimension is three fields, and the resource's alias is the storage spelling
(Quantity_Balance) rather than the published QuantityBalance. The comment two paragraphs above
that loop warns about precisely this drift. Any posting handler that checks stock saw zero and
refused.

Verified end to end. Receipt of 10 / 25 / 40, a sale of 3 and 5, balances reading 7 / 20 / 40 over
five movements — through debug_sandbox in the running client, with the debugger attached and the
writes kept. The commit: true answer also stopped claiming the writes were undone when they were
not (#87): a committed run answers under kept, and a failed one says the failure is why it was
rolled back.

13. The section panel could not be closed — #93

Clicking a section in the client opens its command panel, and nothing put it away again: it stood
over the workspace with the section still lit. With one section in the configuration — where every
configuration starts — there was no way out short of closing the application.

ibSubSystemButton::OnLeftUp ran its body only when the clicked button was not the active one, so
a click on the open section fell through to nothing; and a click on a different section dismissed its
own popup, which is null, rather than the one standing open. The click-outside dismissal a
wxPopupTransientWindow is supposed to perform does not fire here on macOS, so that handler was the
only road and it went nowhere. Separately, OnEventButton built a new popup window per click and
nothing ever deleted one.

The button now toggles, a click on another section closes the open one, Popup clears the
pending-dismiss flag so a window is not reused mid-fade, and a dismissed panel is destroyed.

Verified on screen, and with it the whole arc this branch set out to walk: the section opens and
closes, and Goods balance composed over the seeded base reads Основной склад 67 — tea 20, coffee 7,
sugar 40 — matching the receipt of 10 / 25 / 40 less the sale of 3 and 5.

Verification

Release and Debug builds with -DOES_USE_FIREBIRD=ON -DOES_USE_POSTGRESQL=ON against Firebird 5.0.4 arm64. The designer opens a fresh file infobase, sys.fdb is created, the journal records metadata / applied then session / opened. Adding a common module no longer crashes, verified under the debugger. The Debug designer now starts and serves its MCP endpoint; a configuration of three catalogues, two documents, a balance register and two posting modules was built through it end to end.

⚠ Two of the three Debug fixes are argued, not yet demonstrated. #81 needs a stop to observe and #82 needs the form-editor insertion repeated; both are one-line guards whose reasoning is in the commits, and both should be exercised before this merges. Full suite after every fix here: 1650 tests, 1644 passed, 6 skipped (Firebird batch insert, no live server).

Known, not addressed here

• Embedded Firebird cannot reach its lock directory on macOS — /tmp/firebird is firebird:firebird 0770 and an ordinary user is not in that group, so the designer needs FIREBIRD_LOCK pointed somewhere writable. Firebird's own isql fails identically, so it is not an OES defect, but the fix belongs in ibFirebirdBootstrap::Init(). Reported as macOS: embedded Firebird cannot use its lock directory — /tmp/firebird is firebird:firebird 0770, so startup fails for every ordinary user #73 rather than patched, because the correct default interacts with how a shared file base is coordinated.
• app_run on a file base starts a client that cannot attach — app_run offers a launch that cannot succeed: the designer holds the file base, and the code already knows two processes on one cannot work #86. The launch itself is fixed above; what remains is that the designer holds the base. The designer holds the base; the client exits 1 within a second. The cause turned out to be one Firebird setting, not the platform. ServerMode is left at its shipped default of Super, the one mode that opens a database "exclusive by a single server process"; SuperClassic and Classic both permit the other-process attachment. With a private firebird.conf setting Classic — no sudo, system install untouched — a designer and a thick client run on the same file base simultaneously, zero exceptions, and session_list shows both. So the remaining fix is likely to ship a conf rather than to change any of this code; it has to be decided together with macOS: embedded Firebird cannot use its lock directory — /tmp/firebird is firebird:firebird 0770, so startup fails for every ordinary user #73, since multi-process coordination also needs a writable shared lock directory, which /tmp/firebird is not.
• A startup that cannot take the infobase exits with status 1 and says nothing — A designer that cannot take the infobase exits with status 1 and says nothing — no dialog, no journal line #79. Cause now known for the file-base case, see app_run offers a launch that cannot succeed: the designer holds the file base, and the code already knows two processes on one cannot work #86.
• BUILD_TESTING=ON alone does not produce a linkable suite: test_queryRenderer needs OES_USE_POSTGRESQL=ON too, and nothing states that.

🤖 Generated with Claude Code