neohaskell
diff --git a/‎.github/workflows/claude-code-review.yml‎
Lines changed: 2 additions & 0 deletions b/‎.github/workflows/claude-code-review.yml‎
Lines changed: 2 additions & 0 deletions
diff --git a/‎.gitignore‎
Lines changed: 3 additions & 0 deletions b/‎.gitignore‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎.vscode/extensions.json‎
Lines changed: 0 additions & 1 deletion b/‎.vscode/extensions.json‎
Lines changed: 0 additions & 1 deletion
diff --git a/‎core/nhcore.cabal‎
Lines changed: 25 additions & 0 deletions b/‎core/nhcore.cabal‎
Lines changed: 25 additions & 0 deletions
diff --git a/‎core/service/Integration.hs‎
Lines changed: 6 additions & 0 deletions b/‎core/service/Integration.hs‎
Lines changed: 6 additions & 0 deletions
diff --git a/‎core/service/Service/Application.hs‎
Lines changed: 112 additions & 6 deletions b/‎core/service/Service/Application.hs‎
Lines changed: 112 additions & 6 deletions
@@ -12,6 +12,8 @@ on:
 
 jobs:
   claude-review:
+    # actionlint:ignore:if
+    if: false # Disabled pending Claude Code GitHub App installation — re-enable once the App is installed
     # Optional: Filter by PR author
     # if: |
     #   github.event.pull_request.user.login == 'external-contributor' ||
 
@@ -63,6 +63,9 @@ feature-progress.md
 .pipeline/
 docs/architecture/
 
+# Locally recorded integration fixtures (never commit — may contain real sandbox responses)
+**/tests/fixtures/local/
+
 
 # Node.js / pnpm (website)
 node_modules/
 
@@ -2,7 +2,6 @@
   "recommendations": [
     "streetsidesoftware.code-spell-checker",
     "haskell.haskell",
-    "arrterian.nix-env-selector",
     "esbenp.prettier-vscode",
     "lunaryorn.hlint",
     "davidanson.vscode-markdownlint",
 
@@ -40,6 +40,7 @@ common common_cfg
     dotenv >= 0.11 && < 0.13,
     fast-logger >= 3.0 && < 4,
     file-embed,
+    filepath,
     ghc-prim,
     hashable,
     insert-ordered-containers,
@@ -189,7 +190,12 @@ library
     Integration.Exit
     Integration.Lifecycle
     Integration.Timer
+    Service.Integration.Adapter
     Service.Integration.Dispatcher
+    Service.Integration.DispatchRegistry
+    Service.Integration.IntegrationError
+    Service.Integration.Selection
+    Service.Integration.ShimEmit
     Service.Integration.Types
     IO
     Int
@@ -386,6 +392,7 @@ library
 
   default-language: GHC2021
 
+
 test-suite nhcore-test
   import: common_cfg
   default-language: GHC2021
@@ -537,6 +544,11 @@ test-suite nhcore-test-service
     Service.FileUpload.LifecycleSpec
     Service.FileUpload.ResolverSpec
     Service.FileUpload.RoutesSpec
+    Service.Integration.AdapterSpec
+    Service.Integration.DispatchRegistrySpec
+    Service.Integration.SelectionSpec
+    Service.Integration.TestFixtures
+    Service.Integration.WireupSpec
     Service.MockTransport
     Service.Query.EndpointSpec
     Service.Query.PaginationSpec
@@ -556,14 +568,21 @@ test-suite nhcore-test-service
     Service.Transport.Mcp.ResponseSpec
     Service.MultiTenantSpec
     Service.Transport.WebSpec
+    Service.Transport.Web.HealthCheckSpec
 
   type: exitcode-stdio-1.0
   hs-source-dirs: test-service, test
   main-is: Main.hs
   build-depends:
+    QuickCheck,
+    aeson,
     base,
+    bytestring,
+    directory,
+    filepath,
     hspec,
     nhcore,
+    text,
 
 test-suite nhcore-test-integration
   import: common_cfg
@@ -589,9 +608,11 @@ test-suite nhcore-test-integration
   hs-source-dirs: test-integration, test
   main-is: Main.hs
   build-depends:
+    QuickCheck,
     base,
     hspec,
     nhcore,
+    text,
 
 test-suite nhcore-test-core
   import: common_cfg
@@ -646,6 +667,10 @@ test-suite nhcore-test-core
   hs-source-dirs: test-core, test
   main-is: Main.hs
   build-depends:
+    aeson,
     base,
+    bytestring,
     hspec,
     nhcore,
+    scientific,
+    text,
@@ -96,6 +96,7 @@ import Map qualified
 import Maybe (Maybe (..))
 import Service.Command.Core (NameOf)
 import Service.FileUpload.Core (FileAccessError, FileMetadata, FileRef)
+import Service.Integration.DispatchRegistry (DispatchRegistry)
 import Task (Task)
 import Task qualified
 import Text (Text)
@@ -160,6 +161,11 @@ data ActionContext = ActionContext
   , fileAccess :: Maybe FileAccessContext
   -- ^ File access context for retrieving uploaded files.
   -- 'Nothing' when file uploads are not enabled in the application.
+  , outboundDispatch :: DispatchRegistry
+  -- ^ ADR-0055 registry of pre-bound outbound-integration dispatcher closures.
+  -- Populated once at startup by 'Application.run' based on the
+  -- @--integrations@ CLI flag; read by 'Service.Integration.ShimEmit.emit'.
+  -- Defaults to the empty registry in tests and non-integration contexts.
   }
 
 
 
@@ -3,6 +3,7 @@
 module Service.Application (
   -- * Application Type
   Application (..),
+  IntegrationRegistrationEntry (..),
 
   -- * ServiceRunner Type
   ServiceRunner (..),
@@ -33,6 +34,7 @@ module Service.Application (
   withOutbound,
   withOutboundLifecycle,
   withInbound,
+  withIntegration,
   withAuth,
   withAuthOverrides,
   withApiInfo,
@@ -102,6 +104,12 @@ import System.IO qualified as GhcIO
 import Default (Default (..))
 import GHC.TypeLits qualified as GHC
 import Integration qualified
+import Service.Integration.Adapter (Integration, mkDispatcher)
+import Service.Integration.Adapter qualified as Adapter
+import Service.Integration.DispatchRegistry (DispatchRegistry)
+import Service.Integration.DispatchRegistry qualified as DispatchRegistry
+import Service.Integration.Selection (Selection (..))
+import Service.Integration.Selection qualified as Selection
 import Integration.Lifecycle qualified as Lifecycle
 import Json qualified
 import Map (Map)
@@ -155,6 +163,7 @@ import Text qualified
 import ToText (toText)
 import TypeName qualified
 import Service.Application.Types (ApiInfo (..), defaultApiInfo)
+import Service.Transport.Web (IntegrationStatus (..))
 
 
 -- | Configuration for WebTransport authentication.
@@ -345,6 +354,17 @@ data DeferredInboundReg where
     (config -> Integration.Inbound) ->
     DeferredInboundReg
 
+
+-- | Registration entry for an ADR-0055 Integration type.
+-- Stores the integration name (for hybrid-mode and ERROR logging) and a
+-- function that, given the active Selection, inserts the pre-bound closure
+-- into the DispatchRegistry.
+data IntegrationRegistrationEntry = IntegrationRegistrationEntry
+  { integrationName :: !Text
+  , registerInto :: Selection -> DispatchRegistry -> DispatchRegistry
+  }
+
+
 data Application = Application
   { configSpec :: Maybe ConfigSpec,
     -- | EventStore factory. Resolved during Application.run after config is loaded.
@@ -377,7 +397,9 @@ data Application = Application
     secretStoreFactory :: Maybe SecretStoreFactory,
     -- | Deferred integration registrations. Resolved during Application.run after config is loaded.
     deferredOutboundLifecycleRegs :: Array DeferredOutboundLifecycleReg,
-    deferredInboundRegs :: Array DeferredInboundReg
+    deferredInboundRegs :: Array DeferredInboundReg,
+    -- | ADR-0055 Integration registrations. Built at startup into a DispatchRegistry.
+    integrationRegistrations :: Array IntegrationRegistrationEntry
   }
 
 
@@ -413,7 +435,8 @@ new =
       dispatcherConfigFactory = Nothing,
       secretStoreFactory = Nothing,
       deferredOutboundLifecycleRegs = Array.empty,
-      deferredInboundRegs = Array.empty
+      deferredInboundRegs = Array.empty,
+      integrationRegistrations = Array.empty
     }
 
 
@@ -773,6 +796,9 @@ run app =
          Log.info "Configuration loaded successfully"
            |> Task.ignoreError
 
+     -- 2b. Parse ADR-0055 integration selection from argv and wire DispatchRegistry
+     (registry, maybeIntegrationStatus) <- buildIntegrationContext app
+
      -- 3. Validate EventStore is configured and create it
      eventStore <- case app.eventStoreFactory of
        Nothing -> Task.throw "No EventStore configured. Use withEventStore."
@@ -907,7 +933,7 @@ run app =
            , outboundLifecycleRunners = resolvedOutboundLifecycleRunners
            , inboundIntegrations = resolvedInboundIntegrations
            }
-     runWithResolved eventStore maybeFileUploadSetup fileUploadCleanup maybeWebAuthSetup resolvedApp
+     runWithResolved eventStore maybeFileUploadSetup fileUploadCleanup maybeWebAuthSetup maybeIntegrationStatus registry resolvedApp
 
 
 -- | Run application with a provided EventStore.
@@ -984,14 +1010,16 @@ runWith eventStore app = do
   case Array.isEmpty app.deferredInboundRegs of
     False -> Task.throw "runWith does not support config-dependent inbound integrations. Use Application.run instead, or use: withInbound @() (\\_ -> yourInbound)"
     True -> pass
+  -- Build ADR-0055 DispatchRegistry and integration status (same helper as run)
+  (registry, maybeIntegrationStatus) <- buildIntegrationContext app
   let resolvedApp = app
         { corsConfig = resolvedCorsConfig
         , apiInfo = resolvedApiInfo
         , healthCheckConfig = resolvedHealthCheckConfig
         , dispatcherConfig = resolvedDispatcherConfig
         , secretStore = resolvedSecretStore
         }
-  runWithResolved eventStore maybeFileUploadSetup fileUploadCleanup maybeWebAuthSetup resolvedApp
+  runWithResolved eventStore maybeFileUploadSetup fileUploadCleanup maybeWebAuthSetup maybeIntegrationStatus registry resolvedApp
 
 
 -- | Internal: Run application with pre-resolved EventStore, FileUpload, and Auth.
@@ -1003,9 +1031,11 @@ runWithResolved ::
   Maybe FileUploadSetup ->
   Task Text () ->
   Maybe WebAuthSetup ->
+  Maybe IntegrationStatus ->
+  DispatchRegistry ->
   Application ->
   Task Text Unit
-runWithResolved eventStore maybeFileUploadSetup fileUploadCleanup maybeWebAuthSetup app = do
+runWithResolved eventStore maybeFileUploadSetup fileUploadCleanup maybeWebAuthSetup maybeIntegrationStatus integrationRegistry app = do
   -- 1. Wire all query definitions and collect registries + endpoints + schemas
   wiredQueries <-
     app.queryDefinitions
@@ -1172,6 +1202,7 @@ runWithResolved eventStore maybeFileUploadSetup fileUploadCleanup maybeWebAuthSe
             , Integration.providerRegistry = Integration.fromMap Map.empty
             , Integration.refreshLocks = refreshLocksMap
             , Integration.fileAccess = maybeFileAccessContext
+            , Integration.outboundDispatch = integrationRegistry
             }
         )
     Just (OAuth2Setup envVarName providerFactories) -> do
@@ -1208,6 +1239,7 @@ runWithResolved eventStore maybeFileUploadSetup fileUploadCleanup maybeWebAuthSe
               , Integration.providerRegistry = Integration.fromMap providerMap
               , Integration.refreshLocks = refreshLocksMap2
               , Integration.fileAccess = maybeFileAccessContext
+              , Integration.outboundDispatch = integrationRegistry
               }
       -- Create route handlers with loaded HMAC key and rate limiters
       let routeDeps =
@@ -1281,7 +1313,7 @@ runWithResolved eventStore maybeFileUploadSetup fileUploadCleanup maybeWebAuthSe
   -- When transports complete (or fail), cancel inbound workers for clean shutdown
   -- Use Task.finally to ensure cleanup always runs even if runTransports fails
   result <-
-    Transports.runTransports app.transports combinedEndpointsByTransport combinedSchemasByTransport combinedQueryEndpoints combinedQuerySchemas maybeAuthEnabled maybeOAuth2Config maybeFileUploadEnabled app.apiInfo app.corsConfig app.healthCheckConfig
+    Transports.runTransports app.transports combinedEndpointsByTransport combinedSchemasByTransport combinedQueryEndpoints combinedQuerySchemas maybeAuthEnabled maybeOAuth2Config maybeFileUploadEnabled app.apiInfo app.corsConfig app.healthCheckConfig maybeIntegrationStatus
       |> Task.finally cleanupAll
       |> Task.asResult
 
@@ -1308,6 +1340,48 @@ runWithResolved eventStore maybeFileUploadSetup fileUploadCleanup maybeWebAuthSe
     Ok _ -> Task.yield unit
 
 
+-- | Parse the ADR-0055 @--integrations@ CLI flag and build the
+-- 'DispatchRegistry' from the application's registered integrations.
+--
+-- Also emits the startup 'Log.critical' line when fake or hybrid mode is
+-- active, and returns the 'IntegrationStatus' block that the @/health@
+-- endpoint surfaces (only in fake/hybrid modes — real mode returns
+-- 'Nothing', keeping the health body minimal).
+--
+-- Shared by 'run' and 'runWith' so both entry points wire integrations
+-- identically.
+buildIntegrationContext :: Application -> Task Text (DispatchRegistry, Maybe IntegrationStatus)
+buildIntegrationContext app = do
+  selection <- Selection.parseSelection
+    |> Task.mapError (\err -> [fmt|Integration flag error: #{err}|])
+  let registry =
+        app.integrationRegistrations
+          |> Array.reduce
+              (\entry reg -> entry.registerInto selection reg)
+              DispatchRegistry.empty
+  let maybeStatus = case selection of
+        Real -> Nothing
+        Fake -> do
+          let names = app.integrationRegistrations |> Array.map (\e -> e.integrationName)
+          Just (IntegrationStatus { mode = "fake", fakes = names })
+        Hybrid fakeNames ->
+          Just (IntegrationStatus { mode = "hybrid", fakes = fakeNames })
+  case selection of
+    Real -> pass
+    Fake -> do
+      let names =
+            app.integrationRegistrations
+              |> Array.map (\e -> e.integrationName)
+              |> Text.joinWith ", "
+      Log.critical [fmt|Fake integrations active: #{names}|]
+        |> Task.ignoreError
+    Hybrid fakeNames -> do
+      let names = fakeNames |> Text.joinWith ", "
+      Log.critical [fmt|Fake integrations active: #{names}|]
+        |> Task.ignoreError
+  Task.yield (registry, maybeStatus)
+
+
 -- | Merge two QueryRegistries by combining their updaters.
 mergeRegistries :: QueryRegistry -> QueryRegistry -> QueryRegistry
 mergeRegistries source target = do
@@ -1468,6 +1542,38 @@ withInbound mkInbound app = do
       app {deferredInboundRegs = app.deferredInboundRegs |> Array.push reg}
 
 
+-- | Register an ADR-0055 outbound integration type.
+--
+-- At startup, 'Application.run' parses the @--integrations=@ flag, builds a
+-- pre-bound closure for each registered type, and stores them in a
+-- 'DispatchRegistry'. Domain code then calls 'Service.Integration.ShimEmit.emit'
+-- (or the global wrapper) to dispatch without knowing whether real or fake ran.
+--
+-- Example:
+--
+-- @
+-- app = Application.new
+--   |> Application.withIntegration \@SendEmail
+--   |> Application.withIntegration \@ChargeIntent
+-- @
+withIntegration ::
+  forall request.
+  ( Integration request
+  , Typeable request
+  , Typeable (Adapter.Response request)
+  , TypeName.Inspectable request
+  ) =>
+  Application ->
+  Application
+withIntegration app = do
+  let name = TypeName.reflect @request
+  let registerInto_ selection registry =
+        let closure = mkDispatcher @request selection
+        in DispatchRegistry.register @request closure registry
+  let entry = IntegrationRegistrationEntry { integrationName = name, registerInto = registerInto_ }
+  app {integrationRegistrations = app.integrationRegistrations |> Array.push entry}
+
+
 -- | Enable JWT authentication for WebTransport.
 --
 -- The factory takes a function from your config type to the auth server URL.