---
title: Named sinks
editUrl: https://github.com/Cratis/Stage/edit/main/Documentation/reference/sinks.md
description: How Stage carries Screenplay sink declarations into Chronicle when running or rendering a model, what the manifest lists, and how named-sink reads work.
lastUpdated: 2026-11-15T00:00:00.000Z
---


A Screenplay model can name the sinks its read models and graphs are stored in. `sink Reporting for readmodels` and `sink People for graphs` declare a sink at the application root, and a `sink <Name>` directive in a read model or a graph chooses one. A read model or graph that names no sink uses the default sink of its kind, so a model without sinks behaves exactly as it always has. The model never names an engine: whoever runs the application maps each name to storage, through Chronicle's [named sinks configuration](/chronicle/hosting/configuration/sinks/).

```text
sink Reporting for readmodels
sink People for graphs

module Organization
  feature Chart
    slice StateView Directory
      readmodel Listing
        sink Reporting
        id   PersonId key
        name PersonName
```

## How sinks are carried

Sinks are realization metadata, like `passive`: they sit outside the portable executable model, so adding, changing or removing a `sink` directive leaves the model's ESM bytes and revision unchanged. Stage carries them in `ApplicationRealization.Sinks` (`RealizedSinks`): the declared sinks with their kinds, the sink of each read model that names one, and the sink of each graph that names one.

For rendering, the sinks travel in their own hashed profile input, `cratis-realization:sinks`, so changing a `sink` directive changes the render input hash even though the revision stays the same. A model without sinks adds no input, and its render input hash is the one it always had. Source-backed planning adds the input itself; a programmatic caller uses `CratisRendering.WithRealization(profile, compilation)` or `CratisRendering.WithSinks(profile, compilation)` from the same compilation. A malformed, duplicate, noncanonical or inconsistent input fails profile admission: one that names a read model or graph the model does not declare, a sink the model does not declare, or a sink of the wrong kind.

## Running a model

The semantic engine answers commands and queries over read models in process, so a read model's sink does not change how Stage answers it, and Stage registers no read model with a sink.

Graphs are projected only by the kernel's graph sink. `SemanticGraphMirrors` registers each graph's read model with the kernel and sets the sink name from the model, so a graph that names `People` is registered with `SinkDefinition.Name = "People"`. `Stage__Graph__SinkType` still chooses the sink type, Neo4j by default. The kernel Stage runs against must configure every named graph sink, or it refuses the registration; see [Graph rendering](/stage/reference/graph-rendering/) for the graph sink itself.

## The published package

The package's `manifest.json` lists the declared sinks with their kinds, in declaration order, and an empty list when the model declares none:

```json
"sinks": [
  { "name": "Reporting", "kind": "readmodels" },
  { "name": "People", "kind": "graphs" }
]
```

A runtime that deploys the package uses the list to check that the deployment maps every name before the kernel refuses a registration. The property is additive: the schema version stays `1`, and a manifest written before sinks existed reads as having none. See [Published applications](/stage/reference/published-applications/#manifestjson).

## Rendering

A read model or graph that names a sink renders Chronicle's `[Sink("<Name>")]` attribute: on the read model's record, and on every node and edge record of the graph, since Chronicle requires all elements of one graph to name the same sink. Screenplay refuses a sink on a passive read model (`PLAY0935`), as Chronicle's `CHR0069` refuses `[Sink]` with `[Passive]`.

The rendered `docker-compose.yml` configures the development kernel with one configuration per declared sink, so the rendered application runs without further setup:

| Sink kind | Kernel configuration |
| --- | --- |
| `readmodels` | `Type: MongoDB` on the development image's own MongoDB, `mongodb://localhost:27017` |
| `graphs` | `Type: Neo4j` on the development Neo4j server, `bolt://neo4j:7687`, user `neo4j`, `DatabaseMode: Single`, with the password read from `NEO4J_PASSWORD` as the graph scaffold does |

The variables are `Cratis__Chronicle__Sinks__Configurations__<Name>__*` on the `chronicle` service. The kernel's default sinks are left as they are. A deployment replaces these with its own storage for each name.

The application's `appsettings.json` maps each `readmodels` sink to the same development MongoDB, so the application reads a read model where the kernel writes it, out of the box:

```json
"MongoDB": {
  "Server": "mongodb://localhost:27017",
  "Database": "Organization",
  "Sinks": {
    "Reporting": {
      "Server": "mongodb://localhost:27017"
    }
  }
}
```

The Chronicle client finds a read model's or graph's sink from its `[Sink]` attribute, so its own configuration does not change. A model without `readmodels` sinks gets no `Sinks` section, and `graphs` sinks are never listed there: Arc's MongoDB support only reads read models.

### A query over a read model in a named sink

A rendered query reads its read model through Arc's MongoDB support (`WithMongoDB`). The Arc release Stage pins reads a read model marked `[Sink("<Name>")]` from the server configured for that sink, `Cratis:MongoDB:Sinks:<Name>:Server` (or `ServerFile`, a file holding the connection string, such as a mounted secret). Sink names are case-insensitive. The database name is the one the default connection uses, on the sink's server. Observable queries read the same way. So a query over a read model in a named sink renders like any other query.

A deployment that stores a sink on another server sets that server for the application too, for instance with the environment variable `Cratis__MongoDB__Sinks__Reporting__ServerFile`, next to the kernel's `Cratis__Chronicle__Sinks__Configurations__Reporting__*`.

Graph queries are not rendered at all yet (`STAGE-ESM-068`, see [Graph rendering](/stage/reference/graph-rendering/)): Arc does not read a named Neo4j sink per graph, so a query over a graph is refused whatever sink the graph names.

| Code | Meaning |
| --- | --- |
| `STAGE-ESM-069` | Retired for named sinks. Stage refused a query over a read model in a named sink while its pinned Arc read every rendered query from the application's own database. It is no longer emitted for that since Stage pinned an Arc that reads named sinks, and the number is not reused for it. The same number also names the [secret read model property](/stage/reference/compliance-rendering/) warning, which is still emitted. |
