Question: should Cratis.Stage.Rendering.Cratis depend on Cratis publicly?

[woksin]

Compiling rendered output inside a spec — the thing that caught 1,438 compile errors nobody knew about — required Cratis and Cratis.Arc.MongoDB as references on Rendering.Cratis. Because this repo keeps specs in the project they test, those are normal references, so the published Cratis.Stage.Rendering.Cratis package now takes a dependency on Cratis.

PrivateAssets="All" was tried and is strictly worse: it wins version unification and hides Cratis.Fundamentals from consumers, breaking them at startup.

Three ways out, none obviously right:

1. Leave it. A renderer that emits Cratis code arguably should depend on Cratis, and the alternative below deviates from the repo's layout. Cost: every consumer of the rendering package pulls Cratis and MongoDB whether or not it wants them.
2. A separate Rendering.Cratis.Specs project. Clean — the package stays dependency-free and the spec project takes what it needs. Cost: deviates from this repo's in-project spec convention, which every other project follows.
3. Compile against reference assemblies instead of the real ones. Keeps the spec and the layout, but the compilation is then less faithful than the one that found the bugs.

Worth deciding before the package is more widely consumed, since it is a public dependency either way.

Related: the same spec needed ExcludeAssets="analyzers", because Cratis' type-discovery source generator otherwise bakes a runtime binding into what is fundamentally a text generator.

---

@einari — your call. Option 1 is the status quo and is defensible; option 2 is cleaner but breaks this repo's in-project spec convention.

[woksin]

Measured what option 1 actually costs a consumer, and it is worse than "pulls Cratis and MongoDB whether or not it wants them" — filed as #34 rather than buried here, because it is evidence rather than a question. This issue is the decision; #34 is what the status quo costs.

The short version, from taking the package into the CLI (Cratis/cli#62):

• 160 compilation errors, all ambiguity, because Cratis.props contributes 28 global usings to whatever consumes the renderer;
• MSBL001, because the template engine brings NuGet.Frameworks and Microsoft.Build.Locator refuses to run beside a copy of it;
• and applying the prescribed fix for that makes rendering fail at runtime, because the template engine needs the assembly the locator requires absent. The two engines have opposite requirements about the same file — a consumer can host MSBuild or scaffold from a template, not both.

Two corrections to the framing above, both measured:

PrivateAssets="All" is not "strictly worse" for the reason given. It does not hide Cratis.Fundamentals — that flows in behind Cratis.Screenplay regardless. What it really breaks is subtler: the Release assembly's AssemblyRef table names nine Arc and Chronicle assemblies with 557 type references into them, so a consumer would get unsatisfiable references. Those references are not written by anyone — no production file in Rendering.Cratis names an Arc or Chronicle type — they are a type-discovery registration, which means ExcludeAssets="analyzers" on the two direct references is not stopping the generator. That is a bug in its own right and has to be fixed before either option 1 or option 2 is even evaluable.

Option 2 does not go far enough on its own. Moving the specs to a Rendering.Cratis.Specs project removes Cratis and Cratis.Arc.MongoDB from the package, but leaves Cratis.Templates and the three Microsoft.TemplateEngine.* packages — which are what cause the runtime conflict above. Scaffolding is the heavier dependency, not the spec references.

So there is a fourth option worth putting beside the three: split scaffolding out of the renderer. Rendering into a project the caller already has needs no template engine at all, and that is the common case for regenerating from a document. Rendering.Cratis would then carry Cratis.Screenplay, Cratis.Stage.Contracts and the BCL — consumable anywhere.

[einari]

@woksin Curious; why do we need the full Cratis package? If we need some of the constructs from Arc or Chronicle, we could just add the necessary packages; Cratis.Arc and Cratis.Chronicle. We don't need Mongo and stuff. Or am I missing something here?

[einari]

@woksin I get confused, this issue lives in Stage and the comment refers to CLI. So my previous comment was related to CLI. While Stage when doing its thing for the runtime part - such as running specifications or running a solution would rely on more, obviously. It would need Mongo - but then the CLI is not involved as the runtime engine should be a self contained Docker image that would be involved in the cratis run command.

[woksin]

@einari You're right, and it's most of the way there — I tried it rather than reasoned about it. Branch experiment/narrow-spec-references, 254 specs green, Debug and Release both zero warnings.

Swapping Cratis + Cratis.Arc.MongoDB for the packages actually needed:

<PackageReference Include="Cratis.Arc" ExcludeAssets="analyzers" />
<PackageReference Include="Cratis.Arc.Chronicle" ExcludeAssets="analyzers" />
<PackageReference Include="Cratis.Arc.Swagger" ExcludeAssets="analyzers" />
<PackageReference Include="Cratis.Chronicle" ExcludeAssets="analyzers" />
<PackageReference Include="MongoDB.Driver" />

What it buys

• The global usings stop leaking, which is the big one. Neither Cratis.Arc nor Cratis.Chronicle ships build props; only the meta-package does. That alone removes the 160 ambiguity errors a consumer got — the entire first cost on The renderer package hands every consumer the runtime it generates code for #34.
• Microsoft.Build.Framework, Microsoft.Build.Utilities.Core and Microsoft.NET.StringTools disappear, because they came in behind Cratis.Arc.ProxyGenerator.Build in the meta-package. A text generator has no use for the proxy generator's build-time dependencies.
• 16 fewer packages for a consumer to restore, 186 → 170. Gone with them: Cratis.Chronicle.AspNetCore, handlebars.net, SharpCompress, Snappier, castle.core.

Two things I did miss, and one you did

We do need MongoDB — but the driver, not Cratis.Arc.MongoDB. A rendered read model exposes its collection query the idiomatic way:

public static IQueryable<InvoiceListReadModel> AllInvoiceListReadModels(IMongoCollection<InvoiceListReadModel> collection) => collection.AsQueryable();

so the spec compilation needs MongoDB.Driver on the reference set or every rendered State View stops compiling. MongoDB.Driver alone is 1 package against Cratis.Arc.MongoDB's 6.

Cratis.Arc.Chronicle and Cratis.Arc.Swagger are needed for a reason worth naming, because it is not "rendered code uses them" — it doesn't. They are there so the spec compilation can model the ambient namespaces a real Cratis application has: the harness mirrors the meta-package's GlobalUsings.cs, and two of those 28 lines are Cratis.Arc.Chronicle.Aggregates and Cratis.Arc.Swagger. Drop the packages and only the harness's own global-usings file fails to compile; every rendered file still compiles clean. Modelling the consumer faithfully is the point of that harness, so I kept them — but if you'd rather the renderer not carry them, trimming those two lines is the alternative and it costs only fidelity in the model, not coverage.

What this does not fix, so it isn't mistaken for closing #34:

• The type-discovery generator still runs. The Release assembly's AssemblyRef table still names Cratis.Arc, Cratis.Arc.Chronicle, Cratis.Arc.Core, Cratis.Arc.Swagger, Cratis.Chronicle, Cratis.Chronicle.Connections and Cratis.Chronicle.Infrastructure, with 698 type references into them — no production file in Rendering.Cratis names one. So ExcludeAssets="analyzers" on the direct references is still not stopping it, and PrivateAssets="all" is still unsafe. Whatever contributes that analyzer reaches the compilation another way.
• The template engine is untouched, and it is the half that breaks a consumer at runtime: Cratis.Templates + three Microsoft.TemplateEngine.* still bring NuGet.Frameworks, which Microsoft.Build.Locator refuses to run beside. Scaffolding is what makes this package unhostable, not the Cratis references.

Happy to open the narrowing as its own PR now — it is a strict improvement and independent of the rest. It changes what a consumer restores, so I'd rather you say whether that's a patch or a minor, and whether you want it standalone or folded into splitting scaffolding out.

[einari]

@woksin Better, but do you need the Swagger stuff? If this is for running Specs only. I added a comment on #34 as well - if this is only for specs, the dependencies can be wrapped with conditional of only being there if it's compiled with Debug. That way it won't leak to anything consuming this package.

[woksin]

@einari That works, and it fixes more than the leak — it fixes the half I had wrongly written off as needing separate work. Pushed to experiment/narrow-spec-references.

<ItemGroup Condition="'$(Configuration)' == 'Debug'">
  <PackageReference Include="Cratis.Arc" ExcludeAssets="analyzers" />
  <PackageReference Include="Cratis.Arc.Chronicle" ExcludeAssets="analyzers" />
  <PackageReference Include="Cratis.Arc.Swagger" ExcludeAssets="analyzers" />
  <PackageReference Include="Cratis.Chronicle" ExcludeAssets="analyzers" />
  <PackageReference Include="MongoDB.Driver" />
</ItemGroup>

It is the same condition Directory.Build.props already uses for the test packages and Directory.Build.targets uses to strip the spec files, so the references now come and go with the code that needs them.

Debug: 254 specs green. Release: builds clean, and the package is what it should have been all along.

<dependency id="Cratis.Stage.Contracts" … />
<dependency id="Cratis.Screenplay" … />
<dependency id="Cratis.Templates" … />
<dependency id="Microsoft.TemplateEngine.Abstractions" … />
<dependency id="Microsoft.TemplateEngine.Edge" … />
<dependency id="Microsoft.TemplateEngine.Orchestrator.RunnableProjects" … />

I was wrong about the generator, and this proves how

I said on #34 that ExcludeAssets="analyzers" "is not stopping it — whatever contributes that analyzer reaches the compilation another way", and concluded it needed its own fix before anything else was evaluable. Wrong. It reaches the compilation transitively — ExcludeAssets on a direct reference does not cover an analyzer that arrives behind it — so removing the references removes the generator with them. The Release AssemblyRef table:

	before	after
Arc / Chronicle assemblies referenced	9	0
Cratis.* type references	698	90 (Screenplay + Stage.Contracts, both real)

And package validation names the culprit outright, which is worth reading before deciding the semver:

error CP0001: Type 'Cratis.Arc.Generated.GeneratedMarker' exists on [Baseline]
lib/net10.0/Cratis.Stage.Rendering.Cratis.dll but not on lib/net10.0/…

The generator was not merely baking references — it emitted a public type into the renderer's public surface, and it is in the published 2.3.0 today. So ApiCompat classes its removal as a break, and the build fails until either the suppression file is regenerated or the break is accepted. Your call which, but "removing Cratis.Arc.Generated.GeneratedMarker from a text generator" is not a break anyone can be relying on.

On Swagger — yes, and precisely because rendered code never uses it

The reference set is not "what rendered code needs". It is "what a real Cratis application has ambient", because the harness mirrors the meta-package's 28 global usings so the compilation sees what the rendered file will actually see. Everything in it that rendered code doesn't name is there to catch collisions, and that is not hypothetical — it is how the IIdentityProvider defect surfaced two days ago: Cratis.Arc.Identity and Cratis.Chronicle.Identities both declare one, so the renderer had to name it in full. Nothing rendered references Cratis.Arc.Identity either.

Dropping Swagger would re-open exactly that blind spot for a namespace a rendered [ReadModel] or query could collide with, and now that the references are Debug-only it buys a consumer nothing. I'd keep it — but say the word and I'll drop the package and the matching global-using line together, since leaving one without the other is what breaks the model.

What is left on #34

Only the template engine, and it is the half that actually breaks a consumer at runtime: Cratis.Templates + three Microsoft.TemplateEngine.* bring NuGet.Frameworks, which Microsoft.Build.Locator refuses to run beside — so Cratis/cli#62 still cannot host both. That one is a design question rather than a packaging one: does render scaffold? Rendering into a project the caller already has needs no template engine, and that is the common case for regenerating from a document.

Ready to open as a PR whenever you want it — say patch or minor, and whether to regenerate the ApiCompat suppression or take the break.