diff --git a/CHANGELOG.md b/CHANGELOG.md
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,28 @@
 
 ## [Unreleased]
 
+## 0.26.0.0 — 2026-11-18
+
+### Breaking Changes
+
+- `AppHooks` gains `serviceTopology :: Maybe ServiceTopologyDocument`; direct record
+  constructors must supply it (`Nothing` keeps the previous behavior). Updating
+  `emptyAppHooks` remains the preferred embedding pattern.
+- `Keiro.Ops.Command` gains a `Topology` constructor; exhaustive matches must handle it.
+
+### New Features
+
+- `Keiro.Ops.Topology` mounts an application's committed keiro-dsl service-topology
+  document. `decodeServiceTopology` and `loadServiceTopology` accept schema ids
+  `keiro-dsl/service-topology/1` and `/2`, check the envelope and each id's node kinds
+  and edge relations, and keep the exact bytes. The type, loader, decoder and accessors
+  are re-exported from `Keiro.Ops`.
+- With the hook mounted, `topology show` returns the document and `topology summary`
+  returns a snake_case header with member digests, node and edge counts, and the
+  document's size and SHA-256. Both are reads. HTTP hosts serve `show` as the mounted
+  bytes; the CLI's `--json topology show` re-encodes the decoded value.
+- Adds a direct dependency on `cryptohash-sha256`, already required by `keiro`.
+
 ## 0.25.1.0 — 2026-11-16
 
 ### Other Changes
diff --git a/keiro-ops.cabal b/keiro-ops.cabal
--- a/keiro-ops.cabal
+++ b/keiro-ops.cabal
@@ -1,6 +1,6 @@
 cabal-version: 3.0
 name: keiro-ops
-version: 0.25.1.0
+version: 0.26.0.0
 synopsis: Operational command-line interface for Keiro deployments
 description:
   A standalone database-only console and embeddable command tree for inspecting
@@ -65,6 +65,7 @@
     Keiro.Ops.Snapshot
     Keiro.Ops.Stream
     Keiro.Ops.Timer
+    Keiro.Ops.Topology
     Keiro.Ops.Workflow
     Keiro.Ops.WorkflowHeaderCache
 
@@ -73,13 +74,14 @@
     base >=4.21 && <5,
     bytestring >=0.12 && <0.13,
     containers >=0.6 && <0.8,
+    cryptohash-sha256 >=0.11.102 && <0.12,
     effectful >=2.6 && <2.8,
     effectful-core >=2.6 && <2.7 || >=2.7.1.1 && <2.8,
     hasql >=1.10 && <1.11,
     hasql-pool >=1.4 && <1.5,
-    keiro ^>=0.25.1.0,
-    keiro-migrations ^>=0.25.1.0,
-    keiro-pgmq ^>=0.25.1.0,
+    keiro ^>=0.26.0.0,
+    keiro-migrations ^>=0.26.0.0,
+    keiro-pgmq ^>=0.26.0.0,
     kiroku-store ^>=0.13.0.1,
     optparse-applicative >=0.18 && <0.20,
     text >=2.1 && <2.2,
@@ -113,6 +115,7 @@
   other-modules:
     CategoryConsumersSpec
     ReactionInspectionSpec
+    TopologySpec
 
   build-tool-depends: keiro-ops:keiro-ops
   build-depends:
@@ -120,16 +123,19 @@
     base >=4.21 && <5,
     bytestring >=0.12 && <0.13,
     containers >=0.6 && <0.8,
+    cryptohash-sha256 >=0.11.102 && <0.12,
+    directory >=1.3 && <1.4,
     effectful >=2.6 && <2.8,
     effectful-core >=2.6 && <2.7 || >=2.7.1.1 && <2.8,
+    filepath >=1.4 && <1.6,
     hasql >=1.10 && <1.11,
     hasql-transaction >=1.1 && <1.3,
     hspec >=2.11,
     keiki >=0.9.1 && <0.10,
-    keiro ^>=0.25.1.0,
+    keiro ^>=0.26.0.0,
     keiro-ops,
-    keiro-pgmq ^>=0.25.1.0,
-    keiro-test-support ^>=0.25.1.0,
+    keiro-pgmq ^>=0.26.0.0,
+    keiro-test-support ^>=0.26.0.0,
     kiroku-store ^>=0.13.0.1,
     optparse-applicative >=0.18 && <0.20,
     pgmq-migration >=0.7.0.0 && <0.8,
diff --git a/src/Keiro/Ops.hs b/src/Keiro/Ops.hs
--- a/src/Keiro/Ops.hs
+++ b/src/Keiro/Ops.hs
@@ -4,6 +4,14 @@
     AppHooks (..),
     AggregateInspectors,
     ProcessManagerInspectors,
+    ServiceTopologyDocument,
+    decodeServiceTopology,
+    loadServiceTopology,
+    serviceTopologySchemaId,
+    serviceTopologyBytes,
+    serviceTopologyValue,
+    serviceTopologyDigest,
+    serviceTopologySummary,
     OpsAuditConfig (..),
     emptyAppHooks,
     OpsInvocation (..),
@@ -43,6 +51,17 @@
 import Keiro.Ops.Snapshot qualified as Snapshot
 import Keiro.Ops.Stream qualified as Stream
 import Keiro.Ops.Timer qualified as Timer
+import Keiro.Ops.Topology
+  ( ServiceTopologyDocument,
+    decodeServiceTopology,
+    loadServiceTopology,
+    serviceTopologyBytes,
+    serviceTopologyDigest,
+    serviceTopologySchemaId,
+    serviceTopologySummary,
+    serviceTopologyValue,
+  )
+import Keiro.Ops.Topology qualified as Topology
 import Keiro.Ops.Workflow qualified as Workflow
 import Keiro.Ops.WorkflowHeaderCache (WorkflowHeaderCache, runHeaderCached)
 import Kiroku.Store.Connection (defaultConnectionSettings, withStore)
@@ -90,6 +109,7 @@
   | Stream Stream.Command
   | ReplayAudit ReplayAudit.Command
   | Rebuild Rebuild.Command
+  | Topology Topology.Command
 
 opsCommandTree :: AppHooks -> ParserInfo OpsInvocation
 opsCommandTree hooks =
@@ -144,8 +164,12 @@
         <> rebuildCommand
         <> aggregateCommand
         <> processManagerCommand
+        <> topologyCommand
     )
   where
+    topologyCommand = case hooks.serviceTopology of
+      Nothing -> mempty
+      Just _ -> command "topology" (info (Topology <$> Topology.commandParser) (progDesc "Read the mounted service-topology document"))
     processManagerCommand = case hooks.processManagers of
       Nothing -> mempty
       Just _ -> command "pm" (info (ProcessManager <$> ProcessManager.commandParser) (progDesc "Inspect mounted process managers"))
@@ -218,6 +242,7 @@
   Stream streamCommand -> Stream.isMutation streamCommand
   ReplayAudit _ -> False
   Rebuild rebuildCommand -> Rebuild.isMutation rebuildCommand
+  Topology topologyCommand -> Topology.isMutation topologyCommand
 
 -- | Reuse only pure header presentation after an exact fresh database check.
 -- The optional bytes encode this outcome's successful read result. Other
@@ -247,6 +272,10 @@
       pure $ case encoded of
         Nothing -> (InspectionFailed "inspection_result_too_large" "encoded result exceeds the host limit; narrow the read", Nothing)
         Just body -> (Succeeded result, Just body)
+  -- The committed bytes are the response; never re-encode the document.
+  Topology Topology.Show | Just document <- hooks.serviceTopology -> do
+    outcome <- runCommand hooks env command
+    pure (outcome, Just (serviceTopologyBytes document))
   _ -> runCommandWithHeaderCache cache hooks env command
 
 -- | Execute a parsed command after schema verification. Front ends must use
@@ -274,6 +303,8 @@
       (pure (Failed "projection catalog hook is not mounted"))
       (\operations -> Rebuild.runCommand env operations rebuildCommand)
       hooks.projectionCatalog
+  Topology topologyCommand ->
+    pure (maybe (Failed "service topology hook is not mounted") (\document -> Topology.runCommand document topologyCommand) hooks.serviceTopology)
 
 finishOutcome :: OpsEnv -> OpsOutcome -> IO Exit.ExitCode
 finishOutcome env = \case
diff --git a/src/Keiro/Ops/Embed.hs b/src/Keiro/Ops/Embed.hs
--- a/src/Keiro/Ops/Embed.hs
+++ b/src/Keiro/Ops/Embed.hs
@@ -16,6 +16,7 @@
 import Keiro.Inspection.Consumers (DurableConsumerRegistry)
 import Keiro.Ops.ReplayAudit (OpsAuditConfig (..))
 import Keiro.Ops.Timer (TimerFire)
+import Keiro.Ops.Topology (ServiceTopologyDocument)
 import Keiro.Ops.Workflow (ResumeHook)
 import Keiro.ProcessManager.Inspect (ProcessManagerInspectors)
 import Keiro.Projection.Catalog.Operations (ProjectionCatalogOperations)
@@ -27,7 +28,10 @@
     projectionCatalog :: !(Maybe ProjectionCatalogOperations),
     aggregates :: !(Maybe AggregateInspectors),
     durableConsumers :: !(Maybe DurableConsumerRegistry),
-    processManagers :: !(Maybe ProcessManagerInspectors)
+    processManagers :: !(Maybe ProcessManagerInspectors),
+    -- | The application's committed keiro-dsl service topology. Mounts
+    -- @topology show@ and @topology summary@.
+    serviceTopology :: !(Maybe ServiceTopologyDocument)
   }
 
 emptyAppHooks :: AppHooks
@@ -39,5 +43,6 @@
       projectionCatalog = Nothing,
       aggregates = Nothing,
       durableConsumers = Nothing,
-      processManagers = Nothing
+      processManagers = Nothing,
+      serviceTopology = Nothing
     }
diff --git a/src/Keiro/Ops/Topology.hs b/src/Keiro/Ops/Topology.hs
new file mode 100644
--- /dev/null
+++ b/src/Keiro/Ops/Topology.hs
@@ -0,0 +1,320 @@
+-- | Serve an application's committed keiro-dsl service-topology document.
+--
+-- The document is a published, versioned contract owned by keiro-dsl
+-- (@docs/adr/0062-the-service-topology-is-a-versioned-keiro-owned-contract-emitted-under-the-lowest-sufficient-schema-id.md@).
+-- This module does not depend on keiro-dsl. It checks the envelope fields the
+-- summary needs and each schema id's node-kind and edge-relation vocabulary,
+-- keeps kind-specific details opaque, and retains the exact mounted bytes so
+-- HTTP hosts can return them unchanged.
+module Keiro.Ops.Topology
+  ( ServiceTopologyDocument,
+    decodeServiceTopology,
+    loadServiceTopology,
+    serviceTopologySchemaId,
+    serviceTopologyBytes,
+    serviceTopologyValue,
+    serviceTopologyDigest,
+    serviceTopologySummary,
+    supportedServiceTopologySchemaIds,
+    Command (..),
+    commandParser,
+    isMutation,
+    runCommand,
+  )
+where
+
+import Control.Exception (IOException, try)
+import Crypto.Hash.SHA256 qualified as SHA256
+import Data.Aeson (Value (..), object, (.=))
+import Data.Aeson qualified as Aeson
+import Data.Aeson.Key qualified as Key
+import Data.Aeson.KeyMap (KeyMap)
+import Data.Aeson.KeyMap qualified as KeyMap
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as ByteString
+import Data.ByteString.Builder qualified as Builder
+import Data.ByteString.Lazy qualified as LazyByteString
+import Data.Foldable (toList)
+import Data.Map.Strict qualified as Map
+import Data.Set (Set)
+import Data.Set qualified as Set
+import Data.Text (Text)
+import Data.Text qualified as Text
+import Data.Text.Encoding qualified as Text.Encoding
+import Keiro.Ops.Render
+import Options.Applicative hiding (command, info, value)
+import Options.Applicative qualified as Opt
+
+-- | A mounted keiro-dsl service-topology document: the exact bytes and their
+-- decoded value. Construct only with 'decodeServiceTopology'.
+data ServiceTopologyDocument = ServiceTopologyDocument
+  { bytes :: !ByteString,
+    value :: !Value,
+    schemaId :: !Text,
+    service :: !Text,
+    digest :: !Text,
+    nodeCount :: !Int,
+    edgeCount :: !Int,
+    summary :: !Value
+  }
+
+instance Eq ServiceTopologyDocument where
+  left == right = left.bytes == right.bytes
+
+instance Show ServiceTopologyDocument where
+  show document = "ServiceTopologyDocument " <> show document.schemaId <> " " <> show document.service <> " " <> show document.digest
+
+serviceTopologySchemaId :: ServiceTopologyDocument -> Text
+serviceTopologySchemaId document = document.schemaId
+
+-- | The exact bytes that were mounted, including any final newline.
+serviceTopologyBytes :: ServiceTopologyDocument -> ByteString
+serviceTopologyBytes document = document.bytes
+
+serviceTopologyValue :: ServiceTopologyDocument -> Value
+serviceTopologyValue document = document.value
+
+-- | @sha256:@ and the lowercase hex digest of the mounted bytes.
+serviceTopologyDigest :: ServiceTopologyDocument -> Text
+serviceTopologyDigest document = document.digest
+
+-- | The snake_case summary served by @topology summary@, computed at decode.
+serviceTopologySummary :: ServiceTopologyDocument -> Value
+serviceTopologySummary document = document.summary
+
+-- | Schema ids this reader can mount, oldest first.
+supportedServiceTopologySchemaIds :: [Text]
+supportedServiceTopologySchemaIds = Map.keys vocabularies
+
+data Vocabulary = Vocabulary {nodeKinds :: !(Set Text), relations :: !(Set Text)}
+
+-- Copied from @$defs.nodeKind.enum@ and @$defs.relation.enum@ in
+-- @docs/user/schemas/keiro-dsl-service-topology-{1,2}.schema.json@ so a host
+-- needs only the document. A new schema id or vocabulary requires a change here.
+vocabularies :: Map.Map Text Vocabulary
+vocabularies =
+  Map.fromList
+    [ ("keiro-dsl/service-topology/1", Vocabulary kinds relationsOne),
+      ("keiro-dsl/service-topology/2", Vocabulary kinds (Set.insert "feeds" relationsOne))
+    ]
+  where
+    kinds =
+      Set.fromList
+        [ "aggregate",
+          "process",
+          "workflow",
+          "router",
+          "contract",
+          "intake",
+          "emit",
+          "publisher",
+          "workqueue",
+          "dispatch",
+          "read-model",
+          "operation",
+          "projection-target",
+          "rebuild-group",
+          "projection-owner",
+          "projection-revision",
+          "external-read"
+        ]
+    relationsOne =
+      Set.fromList
+        [ "dispatches",
+          "saga",
+          "reads",
+          "projects",
+          "publishes",
+          "subscribes",
+          "delivers",
+          "enqueues",
+          "commands",
+          "queries",
+          "signals",
+          "runs",
+          "depends-on",
+          "groups",
+          "consumes",
+          "writes",
+          "member-of",
+          "revises",
+          "observes",
+          "backed-by",
+          "exposes",
+          "compatible-with"
+        ]
+
+-- | Decode and check a document for mounting. The diagnostic names the
+-- offending field and value. Additional object fields are ignored.
+decodeServiceTopology :: ByteString -> Either Text ServiceTopologyDocument
+decodeServiceTopology input = do
+  value <- either (\err -> Left ("service topology is not valid JSON: " <> Text.pack err)) Right (Aeson.eitherDecodeStrict input)
+  root <- case value of
+    Object fields -> Right fields
+    other -> Left ("service topology must be a JSON object, found " <> typeName other)
+  schemaId <- textField "schema" root
+  vocabulary <- case Map.lookup schemaId vocabularies of
+    Just known -> Right known
+    Nothing ->
+      Left
+        ( "unsupported service topology schema id "
+            <> quoted schemaId
+            <> " in field `schema`; supported: "
+            <> Text.intercalate ", " supportedServiceTopologySchemaIds
+        )
+  service <- textField "service" root
+  generator <- objectField "generator" root
+  generatorVersion <- prefixed "generator" (textField "version" generator)
+  members <- arrayField "members" root
+  projectedMembers <- traverse member (zip [0 :: Int ..] members)
+  nodes <- arrayField "nodes" root
+  observedKinds <- traverse (node vocabulary) (zip [0 :: Int ..] nodes)
+  edges <- arrayField "edges" root
+  observedRelations <- traverse (edge vocabulary) (zip [0 :: Int ..] edges)
+  let digest = "sha256:" <> hexDigest input
+      sourceField = case KeyMap.lookup "source" root of
+        Just (Object source)
+          | Just (String kind) <- KeyMap.lookup "kind" source,
+            kind `elem` ["source", "workspace"],
+            Just (String path) <- KeyMap.lookup "path" source ->
+              ["source" .= object ["kind" .= kind, "path" .= path]]
+        _ -> []
+      summary =
+        object
+          ( [ "schema_id" .= schemaId,
+              "service" .= service,
+              "generator_version" .= generatorVersion,
+              "members" .= projectedMembers,
+              "node_counts" .= counts observedKinds,
+              "edge_counts" .= counts observedRelations,
+              "document_bytes" .= ByteString.length input,
+              "document_sha256" .= digest
+            ]
+              <> sourceField
+          )
+  Right
+    ServiceTopologyDocument
+      { bytes = input,
+        value,
+        schemaId,
+        service,
+        digest,
+        nodeCount = length nodes,
+        edgeCount = length edges,
+        summary
+      }
+  where
+    member (index, entry) = prefixed (indexed "members" index) $ do
+      fields <- asObject entry
+      path <- textField "path" fields
+      sha256 <- textField "sha256" fields
+      Right (object ["path" .= path, "sha256" .= sha256])
+    node vocabulary (index, entry) = prefixed (indexed "nodes" index) $ do
+      fields <- asObject entry
+      kindOf vocabulary fields
+    edge vocabulary (index, entry) = prefixed (indexed "edges" index) $ do
+      fields <- asObject entry
+      _ <- objectField "from" fields >>= prefixed "from" . kindOf vocabulary
+      _ <- objectField "to" fields >>= prefixed "to" . kindOf vocabulary
+      relation <- textField "relation" fields
+      if Set.member relation vocabulary.relations
+        then Right relation
+        else Left ("field `relation`: unknown relation " <> quoted relation <> " for this schema id")
+    kindOf vocabulary fields = do
+      kind <- textField "kind" fields
+      if Set.member kind vocabulary.nodeKinds
+        then Right kind
+        else Left ("field `kind`: unknown node kind " <> quoted kind <> " for this schema id")
+    indexed name index = name <> "[" <> Text.pack (show index) <> "]"
+    -- Diagnostics from nested fields carry their path, e.g. @edges[3].relation@.
+    prefixed prefix = either (Left . addPrefix prefix) Right
+    addPrefix prefix message = case Text.stripPrefix "field `" message of
+      Just rest
+        | "`" `Text.isPrefixOf` rest -> "field `" <> prefix <> rest
+        | otherwise -> "field `" <> prefix <> "." <> rest
+      Nothing -> message
+    asObject = \case
+      Object fields -> Right fields
+      other -> Left ("field ``: expected an object, found " <> typeName other)
+    counts = Map.fromListWith (+) . map (,1 :: Int)
+
+-- | Read and decode a document from disk. I/O and decode failures are both
+-- returned as 'Left' so callers can report the failing path.
+loadServiceTopology :: FilePath -> IO (Either Text ServiceTopologyDocument)
+loadServiceTopology path = do
+  result <- try (ByteString.readFile path)
+  pure $ case result of
+    Left (err :: IOException) -> Left (Text.pack path <> ": " <> Text.pack (show err))
+    Right input -> either (Left . ((Text.pack path <> ": ") <>)) Right (decodeServiceTopology input)
+
+textField :: Text -> KeyMap Value -> Either Text Text
+textField name fields = case KeyMap.lookup (Key.fromText name) fields of
+  Just (String text) -> Right text
+  Just other -> Left ("field `" <> name <> "`: expected a string, found " <> typeName other)
+  Nothing -> Left ("field `" <> name <> "`: missing")
+
+objectField :: Text -> KeyMap Value -> Either Text (KeyMap Value)
+objectField name fields = case KeyMap.lookup (Key.fromText name) fields of
+  Just (Object inner) -> Right inner
+  Just other -> Left ("field `" <> name <> "`: expected an object, found " <> typeName other)
+  Nothing -> Left ("field `" <> name <> "`: missing")
+
+arrayField :: Text -> KeyMap Value -> Either Text [Value]
+arrayField name fields = case KeyMap.lookup (Key.fromText name) fields of
+  Just (Array items) -> Right (toList items)
+  Just other -> Left ("field `" <> name <> "`: expected an array, found " <> typeName other)
+  Nothing -> Left ("field `" <> name <> "`: missing")
+
+typeName :: Value -> Text
+typeName = \case
+  Object _ -> "an object"
+  Array _ -> "an array"
+  String text -> "the string " <> quoted text
+  Number _ -> "a number"
+  Bool _ -> "a boolean"
+  Null -> "null"
+
+quoted :: Text -> Text
+quoted text = Text.pack (show (Text.unpack (Text.take 120 text)))
+
+hexDigest :: ByteString -> Text
+hexDigest = Text.Encoding.decodeUtf8 . LazyByteString.toStrict . Builder.toLazyByteString . Builder.byteStringHex . SHA256.hash
+
+data Command = Show | Summary
+  deriving stock (Eq, Show)
+
+commandParser :: Parser Command
+commandParser =
+  hsubparser
+    ( Opt.command "show" (Opt.info (pure Show) (progDesc "Print the mounted service-topology document"))
+        <> Opt.command "summary" (Opt.info (pure Summary) (progDesc "Summarize the mounted service-topology document"))
+    )
+
+isMutation :: Command -> Bool
+isMutation = const False
+
+-- | Both reads are pure: the document is fixed for the life of the process.
+-- HTTP hosts serve @show@ from 'serviceTopologyBytes' instead of re-encoding.
+runCommand :: ServiceTopologyDocument -> Command -> OpsOutcome
+runCommand document = \case
+  Show ->
+    Succeeded
+      ( OpsResult
+          ["schema", "service", "nodes", "edges"]
+          [[document.schemaId, document.service, Text.pack (show document.nodeCount), Text.pack (show document.edgeCount)]]
+          document.value
+      )
+  Summary ->
+    Succeeded
+      ( OpsResult
+          ["schema_id", "service", "nodes", "edges", "document_bytes", "document_sha256"]
+          [ [ document.schemaId,
+              document.service,
+              Text.pack (show document.nodeCount),
+              Text.pack (show document.edgeCount),
+              Text.pack (show (ByteString.length document.bytes)),
+              document.digest
+            ]
+          ]
+          document.summary
+      )
diff --git a/test/Main.hs b/test/Main.hs
--- a/test/Main.hs
+++ b/test/Main.hs
@@ -82,6 +82,7 @@
 import System.Exit (ExitCode (..))
 import System.Process (readProcessWithExitCode)
 import Test.Hspec
+import TopologySpec qualified
 
 main :: IO ()
 main = do
@@ -97,7 +98,8 @@
       projectionCatalog = Just emptyCatalogOperations,
       aggregates = Just Map.empty,
       durableConsumers = Nothing,
-      processManagers = Just Map.empty
+      processManagers = Just Map.empty,
+      serviceTopology = Nothing
     }
 
 emptyCatalogOperations :: CatalogOperations.ProjectionCatalogOperations
@@ -121,6 +123,7 @@
 spec fixture = do
   CategoryConsumersSpec.spec fixture
   ReactionInspectionSpec.spec fixture
+  TopologySpec.spec fixture
   describe "embedded command tree" do
     it "omits code-dependent commands from the standalone tree" do
       isParseSuccess (parseOps Ops.emptyAppHooks ["pm", "show", "--name", "test", "--correlation", "one"]) `shouldBe` False
diff --git a/test/TopologySpec.hs b/test/TopologySpec.hs
new file mode 100644
--- /dev/null
+++ b/test/TopologySpec.hs
@@ -0,0 +1,245 @@
+{-# LANGUAGE MultilineStrings #-}
+
+module TopologySpec (spec) where
+
+import Control.Exception (bracket, finally)
+import Control.Monad (forM_)
+import Crypto.Hash.SHA256 qualified as SHA256
+import Data.Aeson (Value (..), object, (.=))
+import Data.Aeson qualified as Aeson
+import Data.Aeson.KeyMap qualified as KeyMap
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as ByteString
+import Data.ByteString.Builder qualified as Builder
+import Data.ByteString.Char8 qualified as Char8
+import Data.ByteString.Lazy qualified as LazyByteString
+import Data.Foldable (toList)
+import Data.Map.Strict qualified as Map
+import Data.Maybe (isJust)
+import Data.Text (Text)
+import Data.Text qualified as Text
+import Data.Text.Encoding qualified as Text.Encoding
+import GHC.IO.Handle (hDuplicate, hDuplicateTo)
+import Keiro.Ops qualified as Ops
+import Keiro.Ops.Render
+import Keiro.Ops.Topology qualified as Topology
+import Keiro.Test.Postgres (Fixture, withFreshDatabase)
+import Options.Applicative qualified as Opt
+import System.Directory (getTemporaryDirectory, removeFile)
+import System.Environment (lookupEnv)
+import System.Exit (ExitCode (..))
+import System.FilePath ((</>))
+import System.IO
+import Test.Hspec
+
+spec :: Fixture -> Spec
+spec fixture = describe "service topology" $ do
+  describe "decodeServiceTopology" $ do
+    it "accepts a /1 document whose aggregate predates the category field" $ do
+      document <- decoded schemaOneDocument
+      Topology.serviceTopologySchemaId document `shouldBe` "keiro-dsl/service-topology/1"
+      Topology.serviceTopologyBytes document `shouldBe` schemaOneDocument
+      Topology.serviceTopologyValue document `shouldBe` json schemaOneDocument
+      Topology.serviceTopologySummary document
+        `shouldBe` object
+          [ "schema_id" .= ("keiro-dsl/service-topology/1" :: Text),
+            "service" .= ("orders" :: Text),
+            "generator_version" .= ("1.2.3" :: Text),
+            "source" .= object ["kind" .= ("source" :: Text), "path" .= ("orders.keiro" :: Text)],
+            "members" .= [object ["path" .= ("orders.keiro" :: Text), "sha256" .= ("sha256:00" :: Text)]],
+            "node_counts" .= object ["aggregate" .= (1 :: Int), "read-model" .= (2 :: Int)],
+            "edge_counts" .= object ["writes" .= (1 :: Int), "consumes" .= (1 :: Int)],
+            "document_bytes" .= ByteString.length schemaOneDocument,
+            "document_sha256" .= ("sha256:" <> hex schemaOneDocument)
+          ]
+
+    it "computes the digest as lowercase hex SHA-256 of the exact bytes" $ do
+      -- The known answer from `printf '{"a":1}\n' | shasum -a 256` checks the
+      -- test's own digest helper independently of the library under test.
+      document <- decoded schemaOneDocument
+      Topology.serviceTopologyDigest document `shouldBe` "sha256:" <> hex schemaOneDocument
+      hex "{\"a\":1}\n" `shouldBe` "e346432021b04179518d9614f3560ccd71354a4ee101ddcb893d6959a9d6301c"
+
+    it "accepts feeds under /2, additional object fields and omits an unknown source shape" $ do
+      document <- decoded schemaTwoDocument
+      Topology.serviceTopologySchemaId document `shouldBe` "keiro-dsl/service-topology/2"
+      let summary = Topology.serviceTopologySummary document
+      field "edge_counts" summary `shouldBe` object ["feeds" .= (1 :: Int)]
+      field "node_counts" summary `shouldBe` object ["intake" .= (1 :: Int), "aggregate" .= (1 :: Int)]
+      KeyMap.member "source" (objectOf summary) `shouldBe` False
+      field "members" summary `shouldBe` Aeson.toJSON ([] :: [Value])
+
+    it "refuses malformed envelopes, unknown ids and unknown vocabulary" $ do
+      let refusals =
+            [ ("{}", "`schema`"),
+              ("[]", "JSON object"),
+              ("{\"schema\":", "not valid JSON"),
+              (withSchema "keiro-dsl/service-topology/9", "\"keiro-dsl/service-topology/9\""),
+              (replaceIn "\"service\":\"orders\"" "\"service\":7" schemaOneDocument, "`service`"),
+              (replaceIn "\"version\":\"1.2.3\"" "\"version\":null" schemaOneDocument, "`generator.version`"),
+              (replaceIn ",\"sha256\":\"sha256:00\"" "" schemaOneDocument, "`members[0].sha256`"),
+              (replaceIn "\"nodes\":[" "\"nodes\":{\"x\":[" (replaceIn "],\"schema\"" "]},\"schema\"" schemaOneDocument), "`nodes`"),
+              (replaceIn "\"kind\":\"aggregate\",\"line\"" "\"kind\":\"saga\",\"line\"" schemaOneDocument, "`nodes[0].kind`: unknown node kind \"saga\""),
+              (replaceIn "\"from\":{\"kind\":\"aggregate\"" "\"from\":{\"kind\":\"actor\"" schemaOneDocument, "`edges[0].from.kind`: unknown node kind \"actor\""),
+              (replaceIn "\"relation\":\"writes\"" "\"relation\":\"pokes\"" schemaOneDocument, "`edges[0].relation`: unknown relation \"pokes\""),
+              (replaceIn "\"keiro-dsl/service-topology/2\"" "\"keiro-dsl/service-topology/1\"" schemaTwoDocument, "unknown relation \"feeds\"")
+            ]
+      forM_ refusals $ \(input, expected) -> case Topology.decodeServiceTopology input of
+        Right _ -> expectationFailure ("accepted " <> Char8.unpack input)
+        Left message -> message `shouldSatisfy` Text.isInfixOf expected
+
+    it "reports a missing file by path" $ do
+      result <- Topology.loadServiceTopology "does/not/exist.topology.json"
+      either (Text.isInfixOf "does/not/exist.topology.json") (const False) result `shouldBe` True
+
+  describe "producer goldens" $ do
+    it "decodes every committed keiro-dsl golden when KEIRO_TOPOLOGY_FIXTURES is set" $ do
+      directory <- lookupEnv "KEIRO_TOPOLOGY_FIXTURES"
+      case directory of
+        Nothing -> pendingWith "set KEIRO_TOPOLOGY_FIXTURES to keiro-dsl/test/fixtures/topology"
+        Just root -> do
+          forM_ goldenFiles $ \relative -> do
+            result <- Topology.loadServiceTopology (root </> relative)
+            either (\err -> expectationFailure (relative <> ": " <> Text.unpack err)) (const (pure ())) result
+          schemas <- traverse (fmap (fmap Topology.serviceTopologySchemaId) . Topology.loadServiceTopology . (root </>)) goldenFiles
+          schemas `shouldSatisfy` elem (Right "keiro-dsl/service-topology/2")
+
+    it "summarizes the hospital golden from independent counts, size and digest" $ do
+      directory <- lookupEnv "KEIRO_TOPOLOGY_FIXTURES"
+      case directory of
+        Nothing -> pendingWith "set KEIRO_TOPOLOGY_FIXTURES to keiro-dsl/test/fixtures/topology"
+        Just root -> do
+          bytes <- ByteString.readFile (root </> "hospital-capacity.topology.golden.json")
+          document <- decoded bytes
+          let summary = Topology.serviceTopologySummary document
+              value = json bytes
+              countBy collection key = Aeson.toJSON (Map.fromListWith (+) [(textAt key item, 1 :: Int) | item <- arrayAt collection value])
+          ByteString.last bytes `shouldBe` 10
+          field "document_bytes" summary `shouldBe` Aeson.toJSON (ByteString.length bytes)
+          field "document_sha256" summary `shouldBe` String ("sha256:" <> hex bytes)
+          field "node_counts" summary `shouldBe` countBy "nodes" "kind"
+          field "edge_counts" summary `shouldBe` countBy "edges" "relation"
+          field "schema_id" summary `shouldBe` String "keiro-dsl/service-topology/1"
+          field "service" summary `shouldBe` String "hospital-capacity"
+          field "source" summary `shouldBe` object ["kind" .= ("source" :: Text), "path" .= ("hospital-capacity.keiro" :: Text)]
+
+  describe "topology commands" $ do
+    it "mounts show and summary only with the hook, as reads" $ do
+      document <- decoded schemaOneDocument
+      let mounted = Ops.emptyAppHooks {Ops.serviceTopology = Just document}
+      forM_ ["show", "summary"] $ \word -> do
+        isJust (parsedCommand Ops.emptyAppHooks ["topology", word]) `shouldBe` False
+        fmap Ops.isMutation (parsedCommand mounted ["topology", word]) `shouldBe` Just False
+        fmap (either (const False) (const True) . Ops.validateCommand) (parsedCommand mounted ["topology", word]) `shouldBe` Just True
+      isJust (parsedCommand mounted ["topology"]) `shouldBe` False
+      isJust (parsedCommand mounted ["topology", "graph"]) `shouldBe` False
+
+    it "returns the document and summary as JSON results" $ do
+      document <- decoded schemaOneDocument
+      jsonOf (Topology.runCommand document Topology.Show) `shouldBe` Just (json schemaOneDocument)
+      jsonOf (Topology.runCommand document Topology.Summary) `shouldBe` Just (Topology.serviceTopologySummary document)
+
+    around (withFreshDatabase fixture) $
+      it "prints the complete document and summary through the normal CLI runner" $ \connectionString -> do
+        document <- decoded schemaOneDocument
+        let mounted = Ops.emptyAppHooks {Ops.serviceTopology = Just document}
+            run word = do
+              invocation <- case Opt.execParserPure Opt.defaultPrefs (Ops.opsCommandTree mounted) ["--database-url", Text.unpack connectionString, "--json", "topology", word] of
+                Opt.Success parsed -> pure parsed
+                _ -> fail "topology command did not parse"
+              captureStdout (Ops.runOpsInvocation mounted invocation)
+        (showExit, shown) <- run "show"
+        showExit `shouldBe` ExitSuccess
+        Aeson.eitherDecodeStrict shown `shouldBe` Right (json schemaOneDocument)
+        (summaryExit, summarized) <- run "summary"
+        summaryExit `shouldBe` ExitSuccess
+        Aeson.eitherDecodeStrict summarized `shouldBe` Right (Topology.serviceTopologySummary document)
+  where
+    decoded bytes = either (fail . Text.unpack) pure (Topology.decodeServiceTopology bytes)
+    jsonOf = \case
+      Succeeded result -> Just result.jsonValue
+      _ -> Nothing
+    parsedCommand hooks args = case Opt.execParserPure Opt.defaultPrefs (Opt.info (Ops.commandParser hooks) mempty) args of
+      Opt.Success command -> Just command
+      _ -> Nothing
+    withSchema schema = replaceIn "\"keiro-dsl/service-topology/1\"" ("\"" <> schema <> "\"") schemaOneDocument
+
+goldenFiles :: [FilePath]
+goldenFiles =
+  [ "hospital-capacity.topology.golden.json",
+    "incident-command.topology.golden.json",
+    "incident-command-sourced.topology.golden.json",
+    "projection-catalog.topology.golden.json",
+    "workspace" </> "service.topology.golden.json"
+  ]
+
+schemaOneDocument :: ByteString
+schemaOneDocument =
+  Char8.pack
+    ( filter
+        (/= '\n')
+        """
+        {"edges":[{"attributes":{},"from":{"kind":"aggregate","name":"Order"},"relation":"writes","to":{"kind":"read-model","name":"order_summary"}},
+        {"attributes":{},"from":{"kind":"aggregate","name":"Order"},"relation":"consumes","to":{"kind":"read-model","name":"order_lines"}}],
+        "effectiveSemanticContract":6,"futureField":{"anything":[1,2]},
+        "generator":{"tool":"keiro-dsl","version":"1.2.3"},
+        "members":[{"declaredLanguageVersion":6,"effectiveLanguageVersion":6,"path":"orders.keiro","sha256":"sha256:00"}],
+        "nodes":[{"context":"orders","details":{"stream":"order"},"kind":"aggregate","line":3,"member":"orders.keiro","name":"Order"},
+        {"context":"orders","details":{},"kind":"read-model","line":9,"member":"orders.keiro","name":"order_summary"},
+        {"context":"orders","details":{},"kind":"read-model","line":12,"member":"orders.keiro","name":"order_lines"}],
+        "schema":"keiro-dsl/service-topology/1","service":"orders","source":{"kind":"source","path":"orders.keiro"}}
+        """
+    )
+    <> "\n"
+
+schemaTwoDocument :: ByteString
+schemaTwoDocument =
+  Char8.pack
+    ( filter
+        (/= '\n')
+        """
+        {"edges":[{"attributes":{"x":1},"from":{"kind":"intake","name":"ingest"},"relation":"feeds","to":{"kind":"aggregate","name":"Order"}}],
+        "effectiveSemanticContract":6,"generator":{"tool":"keiro-dsl","version":"<version>"},"members":[],
+        "nodes":[{"kind":"intake","name":"ingest","details":{}},{"kind":"aggregate","name":"Order","details":{"category":"order"}}],
+        "schema":"keiro-dsl/service-topology/2","service":"orders","source":{"kind":"archive","path":"x"}}
+        """
+    )
+
+replaceIn :: Text -> Text -> ByteString -> ByteString
+replaceIn needle replacement = Text.Encoding.encodeUtf8 . Text.replace needle replacement . Text.Encoding.decodeUtf8
+
+hex :: ByteString -> Text
+hex = Text.Encoding.decodeUtf8 . LazyByteString.toStrict . Builder.toLazyByteString . Builder.byteStringHex . SHA256.hash
+
+json :: ByteString -> Value
+json bytes = either error id (Aeson.eitherDecodeStrict bytes)
+
+objectOf :: Value -> KeyMap.KeyMap Value
+objectOf = \case
+  Object fields -> fields
+  _ -> KeyMap.empty
+
+field :: KeyMap.Key -> Value -> Value
+field key value = maybe Null id (KeyMap.lookup key (objectOf value))
+
+arrayAt :: KeyMap.Key -> Value -> [Value]
+arrayAt key value = case field key value of
+  Array items -> toList items
+  _ -> []
+
+textAt :: KeyMap.Key -> Value -> Text
+textAt key value = case field key value of
+  String text -> text
+  _ -> ""
+
+-- | Run an action with stdout redirected to a temporary file and return it.
+captureStdout :: IO a -> IO (a, ByteString)
+captureStdout action = do
+  directory <- getTemporaryDirectory
+  bracket (openBinaryTempFile directory "keiro-ops-topology.out") (\(path, handle) -> hClose handle `finally` removeFile path) $ \(path, handle) -> do
+    hFlush stdout
+    saved <- hDuplicate stdout
+    result <- (hDuplicateTo handle stdout >> action) `finally` (hFlush stdout >> hDuplicateTo saved stdout >> hClose saved)
+    hClose handle
+    output <- ByteString.readFile path
+    pure (result, output)
