fix(seam): scope the enterprise ImportError arm to the top-level import (#1653)

[dolho]

Fixes #1653.

Related to Abilityai/trinity-enterprise#196 (OSS half; the enterprise half — per-module registration isolation — is Abilityai/trinity-enterprise#197).

The bug

The enterprise load block caught bare ImportError and printed:

Trinity Enterprise submodule not present — OSS-only build
(this is normal; enterprise modules are an optional private submodule)

Correct for an OSS clone. But ImportError also covers a mounted submodule whose module failed to import — e.g. importing a name from an OSS table that hasn't landed yet.

Observed live: the submodule was present and correctly mounted, a module failed, and the operator was told "this is normal" while a paid feature was silently absent. Diagnosing it required hand-running register_enterprise() in the container to see the real traceback.

The fix

Narrow the benign branch to its actual signature — a ModuleNotFoundError whose missing module is the enterprise package:

Situation	Exception	Branch
OSS clone, no submodule	ModuleNotFoundError(name="enterprise.backend")	benign ✓
Module imports a missing name	plain ImportError (not a ModuleNotFoundError)	loud ✓
Module needs an uninstalled package	ModuleNotFoundError(name="pyotp")	loud ✓
Anything else (schema, migration, mount)	Exception	loud ✓ (unchanged)

The loud handler was already correct and is only factored into _report_enterprise_failure() so both paths share it. No behavior change for a genuine OSS build.

Test-pin update

tests/unit/test_847_entitlement_seam.py statically pinned the literal from .sso import register as register_sso + register_sso(app) in the enterprise __init__.py. The paired enterprise PR registers each module through an isolating helper, so that exact pair no longer exists.

The pin moves to the intent — "the submodule registers sso" — and still accepts the pre-ent#196 form, so this cross-repo static check doesn't break on a behavior-preserving refactor in the other repo.

Verification

New tests/unit/test_ent196_enterprise_load_reporting.py (4 passed, 1 skipped — the skip is the "no submodule" case, which can't be exercised in a checkout that has one). Includes a static guard that fails if a bare except ImportError ever comes back in front of the benign message.

Full OSS unit suite: 4667 passed, 16 skipped, 5 failed. All 5 failures reproduce on a clean origin/dev worktree and are unrelated:

• 3× test_admin_email_login — AttributeError: module 'bcrypt' has no attribute '__about__' (local bcrypt/passlib version mismatch)
• test_1474_read_boundary_z::test_schedules_summary_last_run_at_normalized
• test_1472_schedule_validation::test_accepts_valid[0 4 * * *-Europe/Kiev]

Enterprise-docs guard run locally against docs/, CLAUDE.md, main.py, entitlement_service.py — clean (the new comment describes the generic seam and names no module).

Verified live: with the enterprise submodule mounted and one module genuinely broken, the log now reads Trinity Enterprise registration completed with 1 FAILED module(s): … instead of the reassuring line.

🤖 Generated with Claude Code

[dolho]

Extensive testing + one addition

The OSS-only path, verified on a genuinely submodule-less build

The backend image ships without enterprise/ (it's bind-mounted in dev), so I built a real OSS-only tree — src/backend copied minus enterprise/ — and booted it against the same env:

$ docker run --rm --env-file .env -v <oss-tree>:/app <backend-image> \
    sh -c 'python -c "import main"'
Trinity Enterprise submodule not present — OSS-only build (this is normal; …)
IMPORT OK

So the narrowed branch still reports a real OSS clone correctly — the change doesn't regress the case the message exists for.

The loud path was observed live in the opposite direction earlier: with the submodule mounted and Alembic unable to resolve a revision, boot printed Trinity Enterprise registration FAILED — continuing OSS-only: CommandError(...) with a traceback, instead of the reassuring line.

Added: EntitlementService.unregister_module (6bc7f19)

Fault injection against the real register_enterprise (details in Abilityai/trinity-enterprise#197) turned up a third bug: a module that claims its feature_id and then fails leaves a ghost entitlement — advertised by GET /api/settings/feature-flags, UI rendered by the OSS bundle, every call 404s because the router never mounted.

The registering side needs a way to withdraw its own claim, so this adds the edition-agnostic primitive here and the enterprise side uses it (snapshot the registry around each register(), withdraw whatever leaked on failure). Idempotent; withdrawing an unregistered id is a no-op. Nothing in OSS calls it today — it exists for the registering side, same shape as register_module.

3 new tests in test_847_entitlement_seam.py cover withdraw / idempotency / no-collateral-damage.

Suites

• test_847_entitlement_seam.py + test_ent196_enterprise_load_reporting.py → 23 passed, 1 skipped (the skip is the no-submodule case, unreachable in a checkout that has one — covered end-to-end by the container test above instead).
• Enterprise-docs guard re-run against docs/, CLAUDE.md, main.py, entitlement_service.py — clean; the new docstring describes the generic seam and names no module.
• Full OSS unit suite result is unchanged from the PR body: 4667 passed, 5 pre-existing failures that reproduce on a clean origin/dev worktree.

[dolho]

This PR now also fixes #1653 — and #1653's approach found a hole in mine

#1653 (credit @vybe) describes exactly the bug this PR was opened for; I hit it independently while testing trinity-enterprise#196. Reading it, its suggested fix is better than my original one in a case I had wrong, so I've adopted it.

The hole in the name-check-only approach

My first pass kept one try and narrowed the arm to ModuleNotFoundError + "is the missing module the enterprise package?". That mishandles the case the issue is actually about:

scenario	exception	name-check verdict	correct
OSS clone, no submodule	ModuleNotFoundError(name='enterprise')	benign	benign ✓
module imports a missing NAME	plain ImportError	loud	loud ✓
missing third-party dep	ModuleNotFoundError(name='pyotp')	loud	loud ✓
register() imports a missing SIBLING	ModuleNotFoundError(name='enterprise.backend.gone')	benign ← wrong	loud

A module doing from .missing_sibling import x inside register() produces a name whose first segment is enterprise — indistinguishable from an absent submodule by name alone. And lazy imports inside register() are exactly the established pattern the issue cites.

Both parts are needed

• bug: main.py's enterprise except ImportError reports a real registration bug as "submodule not present — this is normal" #1653's structural fix: the ImportError arms guard only the top-level import; register_enterprise(app) moves to the else arm under except Exception. This catches the sibling case — and anything else registration can raise.
• The name check, kept for the top-level import, where structure cannot help: if enterprise/backend/__init__.py needs a third-party package that isn't installed, that's a real failure wearing the same exception type as an absent submodule. bug: main.py's enterprise except ImportError reports a real registration bug as "submodule not present — this is normal" #1653's snippet alone would report it as "this is normal".

Verified live — all four branches

absent submodule (real OSS tree, enterprise/ removed)  -> calm line + IMPORT OK
missing third-party dep in the top-level import        -> diagnostic
from .gone_module import x inside register()           -> diagnostic
   ModuleNotFoundError("No module named 'enterprise.backend.gone_module'")   ← the trap case
the live product_events failure on this instance       -> diagnostic, real cause named

That last one is the bug in the wild: this instance currently has trinity-enterprise#184's telemetry module importing an OSS table whose OSS half (#1721) hasn't merged. Before: "submodule not present — this is normal". After: registration FAILED — ImportError("cannot import name 'product_events' …").

Acceptance criteria (#1653)

• ModuleNotFoundError inside register_enterprise(app) reported as a bug with a traceback naming the module
• Genuinely absent submodule still prints the calm line and boots clean — verified on a real OSS tree, not a mock
• Core boot still survives a broken enterprise module (degrade-don't-crash holds; the live instance is proof)
• Regression tests for both branches

Tests

tests/unit/test_1653_enterprise_load_reporting.py — 7 passed (renamed from the ent#196 file). The structural test parses main.py with ast, not string search: the surrounding comments mention register_enterprise(app) in prose and a substring check matched those (it did, and failed the first run).

Also pins the CI string contract — build-without-submodule.yml greps for "Trinity Enterprise submodule not present", so a reworded message would break CI silently.

Related tests: 87 passed, 3 skipped.

[github-actions]

⚠️ Nightly unit-suite check skipped — merge conflict against dev.

Resolve by running git merge dev locally and pushing the result. The next nightly run will re-test once the conflict is gone.

[vybe]

Validated via /validate-pr: OSS half of the ent#196 seam pair (unregister_module + honest ImportError narrowing), named regression tests, security clean. Enterprise half (ent#197) merged.