Expose a non-owning wrapper factory for an existing cOAPI

[tadoEng]

Why

EtabExtension.CLI Closed Alpha remediation has reached a real lifecycle boundary that EtabSharp 0.3.5-beta cannot express safely.

Live evidence in tadoEng/EtabExtension.CLI#15 showed the managed path Process.Start(ETABS.exe) -> ETABSWrapper.ConnectToProcess(pid) could return an object whose SapModel existed but was not API-ready: cSapModel.InitializeNewModel threw and ApplicationExit(false) returned -1 on the same freshly attached object. Cardex ETABS 23.3 evidence confirms cHelper.CreateObject(path) starts the target program, cOAPI.ApplicationStart() is the explicit startup call, and InitializeNewModel is for a properly created API object.

The CLI therefore needs to own the raw CSI lifecycle (cHelper / cOAPI) and exact OS-process identity, then hand the same already-created, already-started cOAPI to EtabSharp for model/domain abstractions. EtabSharp 0.3.5-beta has no public way to do that: ETABSApplication(cOAPI, ...) is internal.

Do not solve this by using CreateNew(startApplication:true): current CreateNew logs but does not propagate nonzero ApplicationStart, and the CLI needs the raw return code as part of its safety contract. Do not use ConnectToProcess: its GetObjectProcess path can fall back to ROT GetObject, which is incompatible with exact-PID ownership.

Required API

Add one deliberately low-level public factory, conceptually:

public static ETABSApplication WrapExisting(
    cOAPI api,
    int majorVersion,
    double apiVersion,
    string fullVersion,
    ILogger<ETABSApplication>? logger = null)

Exact naming may differ, but the semantics must not.

Contract

This method is pure wrapping. It must:

• validate api and supplied metadata;
• construct the existing ETABSApplication around that exact cOAPI;
• use the existing api.SapModel path;
• preserve the exact object identity supplied by the caller.

It must not:

• call cHelper.CreateObject*;
• call ApplicationStart;
• call GetObject, GetObjectProcess, or any ROT attach;
• enumerate or select ETABS processes;
• call Hide / Unhide;
• call ApplicationExit;
• silently create or attach to another ETABS instance.

Keep the ETABSApplication constructor internal; the public entry point should communicate the non-owning/raw-interop intent clearly.

Ownership / disposal

The caller owns application lifecycle. Wrapping an existing cOAPI must not imply that EtabSharp owns process startup or shutdown. Current ETABSApplication.Dispose() only releases COM references; preserve that non-exiting behavior.

Document that callers must perform lifecycle calls themselves when using this factory.

Verification

• API is additive; existing Connect / ConnectToProcess / CreateNew behavior remains unchanged in this issue.
• Add focused tests/documentation proving the new factory does not bootstrap or attach another application.
• Build/test both supported targets.
• No live ETABS mutation is needed merely to prove the factory surface.
• Use Cardex for any CSI API fact referenced during implementation; do not commit proprietary/generated Cardex content.

Downstream

This is a blocking dependency for EtabExtension.CLI TAD-19 / PR #15. After this change is reviewed, release it as the next beta package version (expected 0.3.6-beta, unless repository release policy dictates otherwise), then the CLI can implement raw CSI startup + exact OS ownership + InitializeNewModel before wrapping the proven-ready handle.

[tadoEng]

Implementation authorized — Claude owns #1; Dispose contract corrected

Collision check before dispatch:

• issue Expose a non-owning wrapper factory for an existing cOAPI #1 is open and unassigned;
• no open EtabSharp PRs exist;
• current master is still baa07045b145cdbcc7fb25314211e7455718428e;
• no competing writer is recorded.

Claude is authorized to implement this issue from that exact base in an isolated branch/worktree.

Important correction: ETABSApplication.Dispose()

Verified at v0.3.5_beta / current master: Dispose() does not call ApplicationExit(false). It releases COM references only. The XML documentation above it is stale and incorrectly says Dispose exits ETABS.

Fix that stale documentation in this issue because it has already caused downstream design drift.

Correct lifecycle rule:

Dispose() is a COM-reference release operation. It must never be used as a substitute for, or before, the caller's authoritative application exit. For a caller-owned raw cOAPI, perform the authoritative ApplicationExit(false) decision/check first, then dispose/release the EtabSharp wrapper/COM references when it is safe to do so.

For EtabExtension.CLI Defect C this matters because Cardex's cOAPI.ApplicationExit(bool) contract requires model references to be released afterward. A pure COM-release Dispose() is therefore the correct post-exit cleanup step; the downstream blanket "never call Dispose" rule will be corrected separately.

Implementation scope

Create the narrow pure-wrapping factory from the issue contract. Keep the existing constructor internal. The new path must consume the exact supplied cOAPI and must perform no lifecycle or discovery work: no CreateObject*, ApplicationStart, GetObject*, ROT fallback, process enumeration, Hide/Unhide, or ApplicationExit.

Also correct only the stale lifecycle documentation needed to make Dispose() semantics truthful. Do not broaden this issue into changes to existing Connect, ConnectToProcess, or CreateNew behavior.

Use Cardex for any CSI API fact referenced in implementation/docs; do not commit proprietary/generated Cardex material.

Verification / handback

Required before handback:

• focused tests proving the public factory is additive and pure wrapping;
• prove caller-supplied cOAPI is the object used by the resulting wrapper (no reattach/recreate path);
• validate argument/metadata behavior deliberately rather than through hidden discovery;
• build/test both supported targets (net8.0, net10.0);
• package/build checks required by this repo;
• exact base/head/diff and test results in this issue + PR.

Do not publish/release 0.3.6-beta yet. Open the PR and stop for lead exact-head review. Release/version publication is a separate post-review step.

[tadoEng]

Implemented in #2 at exact head 95e2d026dfd158ac9886a8b461947dfb95ffc338 (base baa07045b145cdbcc7fb25314211e7455718428e).

WrapExisting is pure wrapping — the only member it touches on the caller's object is SapModel, the ETABSApplication constructor stays internal, and a DispatchProxy recorder proves the negative rather than asserting it by inspection. The stale Dispose() XML comment is corrected to the real contract.

Evidence: library builds clean on net8.0 and net10.0 (293 warnings each, identical to the baa07045 baseline — zero added); offline suite 12/12 on both frameworks; dotnet pack produces both lib folders with ETABSv1.dll not bundled; zero ETABS processes before and after. No version bump (the release workflow takes it from the tag) and no publish. Full detail in the PR.