feat(server): server foundations — layout, Modulith, SQL tenancy, runtime roles

[FelixTJDietrich]

Description

Lays the structural foundation for the next phase of server consolidation. Flattens
the repo layout (server/, webhook-ingest/ at root), renames the Java base package
to match the current chair (de.tum.cit.aet.hephaestus), adopts Spring Modulith 2.0
with module boundaries verified on every PR, introduces SQL-layer multi-tenancy via a
WorkspaceStatementInspector, formalises a two-role runtime topology (server /
worker) gated by @ConditionalOnProperty, and tightens the sandbox SPI.

These are not user-facing features — they are the invariants every subsequent epic
will assume. Behaviour is unchanged for end users; the rename moves files, the
Modulith work declares boundaries, the tenancy work asserts an existing invariant,
and the runtime-role work introduces seams that today still resolve to "everything
runs in one JVM".

Fixes #1097

What changed

Layout + package (mechanical):

• server/application-server/ → server/; server/webhook-ingest/ → webhook-ingest/
• Java base package de.tum.in.www1.hephaestus → de.tum.cit.aet.hephaestus
• Maven artifactId hephaestus → hephaestus-server

Liquibase: master.xml retained with explicit <include> per changelog in the
same historical apply order as main (no <includeAll/> switch). Two PRs that add
migrations in parallel produce a natural merge conflict in master.xml, forcing the
authors to agree on order — <includeAll/> would silently interleave them
lexicographically.

Spring Modulith 2.0:

• Every top-level package declares @ApplicationModule
• 5 modules narrowed from Type.OPEN to default CLOSED with explicit @NamedInterface
  declarations (integrations.posthog, activity.scoring, core.{exception,security,proxy,runtime,event},
  practices.{model,spi,review,finding}, workspace.{context,authorization,spi,settings})
• config + gitprovider remain Type.OPEN (genuine shared kernels — narrowing
  requires a separate epic given their 1000+ external imports)
• ModulithVerificationTest runs in the architecture surefire group on every PR
• SecurityUtils moved from root package → core/security/ to break a root↔workspace
  cycle that surfaced once workspace closed

SQL-layer multi-tenancy (core/tenancy/):

• WorkspaceStatementInspector (Hibernate StatementInspector) asserts every SQL
  statement against a workspace-scoped table carries a workspace_id predicate.
  Regex-only pipeline (no SQL parser dependency): bypass-check → mode-OFF → Caffeine
  cache → INSERT short-circuit → PK-anchored DML/SELECT short-circuit →
  workspace_id word-boundary fast path → table-extract fallback. Fail-open on
  pathological input via the tenancy.parse_failure.total counter (the inspector
  itself must never throw).
• JSqlParser was tried and rejected — adding it to the classpath caused Spring
  Data JPA to auto-activate JSqlParserQueryEnhancer, which threw on legitimate
  Postgres-escaped @Query natives (e.g., CONCAT(:id\:\:text, ...)) and broke
  application boot.
• Three carve-outs anchored on the surrogate-key invariant (you only obtain an id
  via a workspace-scoped path, so PK-anchored DML/SELECT and INSERTs whose value
  list carries workspace_id are safe by construction): INSERT, WHERE id = ? DML
  (with optional optimistic-lock version = ?), and WHERE alias.id = ? SELECTs
  (the EntityManager.find / lazy fetch shape). Each pattern is intentionally narrow;
  any additional non-PK predicate falls through to the standard workspace_id
  check.
• WorkspaceScopedTables is the single source of truth — populated at startup from
  Hibernate's MappingMetamodel, covering entities AND many-to-many @JoinTable
  collections (so SELECT * FROM issue_label cannot leak labels across workspaces).
  Fails fast if the metamodel call chain regresses.
• @WorkspaceAgnostic is now load-bearing: WorkspaceAgnosticAspect
  (@Order(HIGHEST_PRECEDENCE)) opens a TenancyBypass scope so cross-workspace
  queries pass the inspector cleanly. The aspect resolves the annotation across
  inherited Spring Data interface methods, so annotating a repository (or one of
  its parents) is sufficient. Dropping the annotation from a repository now
  causes a TenancyViolationException under enforcement=throw.
• Repositories that scope through FK chains rather than a direct workspace_id
  column are marked @WorkspaceAgnostic (each carries a one-line rationale on the
  type) — same defect class is caught one hop up, on the parent's workspace_id
  predicate.
• Three modes via hephaestus.tenancy.enforcement — throw (default in test),
  log (default elsewhere; Micrometer counter tenancy.violation.total{table, mode}
  observable), off.
• WorkspaceScopedTablesParityTest (ArchUnit) prevents drift between the production
  allowlist and the existing arch-test entity list.

Runtime roles (core/runtime/):

• hephaestus.runtime.server.enabled and hephaestus.runtime.worker.enabled
  property keys + capability flag hephaestus.sandbox.llm-proxy.enabled
• All default matchIfMissing=true (enforced by RuntimeRoleBoundaryTest — a
  fresh JAR with zero env vars boots a full monolith; operators opt OUT, not IN)
• Three boundary refactors for the future split:
  • AgentNatsConfiguration split into connection (always-on) + consumer
    (worker-only)
  • DockerSandboxConfiguration gated by the worker-role property
  • LlmProxyController + LlmProxySecurityConfig gated by the capability flag

Sandbox SPI tightening:

• NetworkPolicy is a record with typed URL validation in the compact constructor
  (rejects relative URLs and non-http(s) schemes at SPI build time; preserves
  ${placeholder} template support for @ConfigurationProperties binding)

Documentation:

• 7 ADRs under docs/decisions/ (MADR format) capture: flat top-level layout,
  Java package rename, Modulith adoption, SQL-layer tenancy, two-role runtime
  topology, LLM-proxy-on-coordinator trust model, sandbox SPI shape
• Root AGENTS.md updated (Spring Boot 4, Node 24, pnpm 11, architecture-tests
  Maven profile)

Tests:

• New unit tests covering TenancyBypass, WorkspaceStatementInspector (regex
  pipeline + every carve-out + regression for composite-key tuple-IN and
  Postgres \:\:text casts), NetworkPolicy, WorkspaceScopedTables (including
  fail-fast guard)
• RuntimeRoleBoundaryTest mutation-verified: introducing
  matchIfMissing=false on a hephaestus.runtime.* gate now fails the build
• WorkspaceScopedTablesParityTest prevents SSOT drift

How to test

• cd server && ./mvnw -Parchitecture-tests test — architecture tests (Modulith
  verify + runtime-role boundary + tenancy parity + existing ArchUnit suites)
• cd server && ./mvnw test — full unit suite includes the new tenancy tests
• pnpm run format:check — clean across webapp, server, webhook-ingest
• The single-JVM monolith continues to boot exactly as before: every runtime gate
  defaults matchIfMissing=true, so no env-var changes are needed locally or in
  staging. Future split deploys flip flags only.

Notable scope cuts (deferred — filed as follow-ups in #1097 sub-issues)

• @TenantId Hibernate native multi-tenancy — needs multi-hop workspace_id
  denormalisation on 20+ entities; separate 6-12 week epic
• MockMvc-driven CrossWorkspaceIsolationTest — fixture work meaningful enough
  to deserve its own PR; the SQL-layer inspector covers the same defect class
• SecretMount / EmptyDirMount / ConfigMapMount — speculative API surface
  with zero current consumers; lands with the K8s adapter epic
• WorkerAuthProvider BYO-runner SPI — premature; needs real BYO requirements
• Multi-replica scheduler with leader election — single-replica today; ShedLock
  out of scope

These are deliberate scope cuts (documented in the ADRs), not unfinished work.

Risks

• Rename merge bill. Long-running epics across a directory rename are painful;
  merge soon to limit drift.
• Inspector regex carve-outs. Four patterns (INSERT, PK-only DML, PK-anchored
  SELECT, workspace_id word-boundary) are holes in the SQL-tenancy wall by
  design. Each is anchored on a documented invariant; any additional non-PK
  predicate falls through to the standard check. Worth a reviewer pass.
• @WorkspaceAgnostic on FK-chain repositories. Each annotated repository
  bypasses the inspector entirely. Rationale is one-line per type; reviewer pass
  recommended.
• Hibernate @Incubating MappingMetamodel API. WorkspaceScopedTables fails
  fast if the call chain ever regresses — silent fall-through to a no-op inspector
  is the worst possible failure mode.
• Surefire fork timeout bumps (21f8c4693) cleared a pre-existing unit+arch
  fork-timeout failure without diagnosing the leak. Tracked as follow-up debt.

🤖 Generated with Claude Code

[FelixTJDietrich]

🎉 This PR is included in version 0.71.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀