@cratis/pi 7.36.1 → 7.38.0

package/package/corpus/skills/cratis-fundamentals-telemetry/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: cratis-fundamentals-telemetry
+description: Instrument a .NET service with Cratis.Metrics.Roslyn generated counters, gauges, histograms and spans, and subscribe/export them through Cratis.OpenTelemetry. Use for partial instrumentation declarations, missing telemetry, host setup or metric-name upgrades. Do not use for operating a collector or for application audit records.
+license: MIT
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Generated metrics and traces
+
+Use this when a service needs measurements and spans, not business facts. Keep event sourcing and audit records separate from telemetry.
+
+## Verified product sources
+
+All source locators below are in **Cratis/Fundamentals v7.23.0**. Read the tag, not a sibling checkout's HEAD.
+
+| Package | Version | Source |
+| --- | --- | --- |
+| `Cratis.Fundamentals` | `7.23.0` | `Source/DotNET/Fundamentals/Metrics/{Counter,Gauge,Histogram}Attribute.cs`, `Traces/SpanAttribute.cs`, `Diagnostics/TagAttribute.cs` |
+| `Cratis.Metrics.Roslyn` | `7.23.0` | `Source/DotNET/Metrics.Roslyn/MetricsSourceGenerator.cs:42-130,174-238,285-337,354-406`; `Templates/Metrics.hbs:11-123` |
+| `Cratis.OpenTelemetry` | `7.23.0` | `Source/DotNET/OpenTelemetry/OpenTelemetryExtensions.cs:29-180,215-315`; `InstrumentationExtensions.cs:17-31`; `CratisOpenTelemetryOptions.cs:19-34` |
+
+Registration evidence: `Source/DotNET/Fundamentals/DependencyInjection/ServiceCollectionExtensions.cs:27-54`. Unkeyed names: `Metrics/UnkeyedMeter.cs:17-23`, `Traces/UnkeyedActivitySource.cs:17-23` under the same Fundamentals source root. Upgrade context: `Documentation/csharp/metrics/roslyn.md` (Exported Metric Names) and `Documentation/csharp/opentelemetry.md`.
+
+## 1. Declare instrumentation beside its owner
+
+Reference `Cratis.Fundamentals` for runtime types and `Cratis.Metrics.Roslyn` for generation. Use a **static partial class in a namespace**, containing **static partial methods**. The generator's candidate filter requires static classes even for metrics; a merely partial instance class is not enough (`MetricsSourceGenerator.cs:42-53,84-93`). Prefer extension declarations with short, unqualified attribute/type names, as below.
+
+This declaration file is complete; it assumes the application's existing `ReportWorker` class in `MyApplication.Reports`:
+
+```csharp
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using System.Diagnostics;
+using Cratis.Diagnostics;
+using Cratis.Metrics;
+using Cratis.Traces;
+
+namespace MyApplication.Reports;
+
+public static partial class ReportInstrumentation
+{
+    [Counter<int>("reports.completed", "Completed reports")]
+    internal static partial void Completed(this IMeter<ReportWorker> meter,
+        [Tag("reports.outcome")] string outcome);
+
+    [Gauge<int>("reports.pending", "Pending reports")]
+    internal static partial void Pending(this IMeter<ReportWorker> meter, int count);
+
+    [Histogram<double>("reports.duration", "Report duration", "s")]
+    internal static partial void Duration(this IMeter<ReportWorker> meter, double seconds);
+
+    [Span("reports.build", ActivityKind.Internal)]
+    internal static partial IActivityScope<ReportWorker> Build(
+        this IActivitySource<ReportWorker> source,
+        [Tag("reports.format")] string format);
+}
+```
+
+- The first metric argument is `IMeter<T>` or `IMeterScope<T>`. A counter without a measurement increments by one. The first remaining parameter, in any position, whose type exactly matches the attribute's numeric type is the measurement, not a tag; avoid a second parameter of that type. Gauges and histograms require that measurement (`MetricsSourceGenerator.cs:285-337`).
+- Remaining parameters are tags. Metric keys default to parameter names; span keys default to snake_case. `[Tag("key")]` from `Cratis.Diagnostics` overrides either (`:174-185,403`).
+- `IMeterScope<T>` merges scope tags with method tags (`Templates/Metrics.hbs:34-38,67-71,96-100`). Do not put credentials, personal payloads or unbounded entity IDs in metric labels; choose bounded categories.
+- Name, description and optional UCUM unit are distinct. A duration in seconds uses `"s"` and a measurement in seconds, not milliseconds (`HistogramAttribute.cs:14-29`, template `:109`).
+- A span returns `IActivityScope<T>` and takes `IActivitySource<T>` first. Assign the returned scope with `using`; `CRT0001` checks disposal (`ActivityScopeUsingAnalyzer.cs:20`, `Templates/Metrics.hbs:118-122`).
+
+Call-site excerpt inside the existing worker, with injected `IMeter<ReportWorker> meter` and `IActivitySource<ReportWorker> source`:
+
+```csharp
+using var activity = source.Build("pdf");
+meter.Pending(3);
+meter.Completed("succeeded");
+meter.Duration(0.25);
+```
+
+This shows recording, not report execution. Both `AddBindingsByConvention()` and `AddSelfBindings()` register unkeyed `IMeter<>` and `IActivitySource<>` as singletons. For a plain host, use the normal type-discovery/convention setup from **cratis-fundamentals-type-discovery**; a generated method alone does not register its dependencies.
+
+## 2. Subscribe the actual instrumentation name
+
+**Unkeyed instruments use `typeof(T).FullName`**, not the metric name and not the host service name. `AddCratisInstrumentation()` subscribes only to `Cratis.*`. An application namespace such as `MyApplication.Reports.ReportWorker` needs an explicit meter/source subscription. This is the first check when generation works but nothing is exported.
+
+Reference `Cratis.OpenTelemetry` explicitly for SDK/exporter setup. Host-setup excerpt for an existing `IHostApplicationBuilder builder` (including a `WebApplicationBuilder`), before building the host:
+
+```csharp
+using Cratis.OpenTelemetry;
+using OpenTelemetry.Metrics;
+using OpenTelemetry.Trace;
+using MyApplication.Reports;
+
+builder.AddCratisOpenTelemetry(options =>
+{
+    options.ServiceName = "report-service";
+    options.ConfigureMetrics = metrics => metrics.AddMeter(typeof(ReportWorker).FullName!);
+    options.ConfigureTracing = tracing => tracing.AddSource(typeof(ReportWorker).FullName!);
+});
+```
+
+`AddCratisOpenTelemetry` extends `IHostApplicationBuilder`. When the host already owns an OpenTelemetry builder, use `services.AddOpenTelemetry().WithCratis(configuration, configure)` instead; `WithCratis` extends `OpenTelemetryBuilder`. Do not add both setups. If the application only wants subscription helpers, `AddCratisInstrumentation()` extends both `TracerProviderBuilder` and `MeterProviderBuilder`, not the service collection (`OpenTelemetryExtensions.cs:29-71`, `InstrumentationExtensions.cs:24-31`).
+
+Shared setup adds Cratis sources/meters, ASP.NET Core and HTTP client instrumentation, runtime metrics, and scoped/formatted logs. Application callbacks run before DI is built (`OpenTelemetryExtensions.cs:77-180`).
+
+## 3. Configure export, without baking endpoints or secrets into code
+
+At this tag, OTLP export is **opt-in**: no configured endpoint means no OTLP exporter. Environment values take precedence over configuration keys. Relevant standard keys (`OpenTelemetryExtensions.cs:215-315`):
+
+| Key | Effect |
+| --- | --- |
+| `OTEL_SERVICE_NAME`, `OTEL_RESOURCE_ATTRIBUTES` | Resource values override application defaults |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Shared absolute HTTP/HTTPS endpoint |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `_METRICS_ENDPOINT`, `_LOGS_ENDPOINT` | Signal-specific endpoints override the shared endpoint |
+| `OTEL_EXPORTER_OTLP_PROTOCOL` (or signal-specific equivalent) | `http/protobuf` selects HTTP; otherwise gRPC |
+| `OTEL_TRACES_EXPORTER`, `OTEL_METRICS_EXPORTER`, `OTEL_LOGS_EXPORTER` | If supplied, must include `otlp` for that signal to export |
+| `OTEL_SDK_DISABLED=true` | Disables providers |
+| `OTEL_METRIC_EXPORT_INTERVAL`, `OTEL_METRIC_EXPORT_TIMEOUT` | Metric reader timing in milliseconds |
+| `OTEL_TRACES_SAMPLER`, `OTEL_TRACES_SAMPLER_ARG` | Sampler and ratio configuration |
+
+For HTTP/protobuf, the shared endpoint gains `/v1/traces`, `/v1/metrics` or `/v1/logs`; signal-specific endpoints are used as supplied. An enabled invalid endpoint throws `InvalidOpenTelemetryEndpoint`. Treat exporter headers as secrets; obtain them through the approved environment/secret mechanism, never a snippet or committed configuration.
+
+## Upgrade and prove it
+
+- Fundamentals stopped bringing the OpenTelemetry SDK transitively in **7.20.2**; add the explicit telemetry package when migrating a consumer that relied on that dependency (`Documentation/csharp/opentelemetry.md`).
+- Regeneration after the **7.20.0** unit correction can rename exported Prometheus metrics: descriptions are now HELP text, not units. Rebuild the consumer and update dashboards/alerts that used the old description-suffixed names (`metrics/roslyn.md`, template `:48-50,80,109`).
+- Build with analyzers and warnings as errors. Inspect generated implementations for correct measurements/tags and scope disposal. Do not edit generated files.
+- Exercise one code path with a listener or the configured collector: observe the counter increment, histogram unit/measurement and completed span. A build or `skill-contains` assertion is not proof of export. Check namespace subscriptions, SDK disablement, sampler and endpoint independently before diagnosing the collector.

package/package/corpus/skills/cratis-fundamentals-telemetry/verification.json

@@ -0,0 +1,15 @@
+{
+  "skill": "cratis-fundamentals-telemetry",
+  "input": "Generate service metrics and spans and diagnose why an application's unkeyed meter is not exported.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "static partial class in a namespace" },
+    { "kind": "skill-contains", "value": "Histogram<double>" },
+    { "kind": "skill-contains", "value": "IActivityScope<ReportWorker>" },
+    { "kind": "skill-contains", "value": "CRT0001" },
+    { "kind": "skill-contains", "value": "typeof(T).FullName" },
+    { "kind": "skill-contains", "value": "AddCratisOpenTelemetry" },
+    { "kind": "skill-contains", "value": "no configured endpoint means no OTLP exporter" },
+    { "kind": "skill-contains", "value": "descriptions are now HELP text, not units" }
+  ]
+}

package/package/corpus/skills/cratis-orleans-jobs/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: cratis-orleans-jobs
+description: Build recoverable work with Cratis.Orleans jobs and job-step grains, stage barriers, bounded startup and cleanup, storage scopes and state machines. Use for service or kernel job authors, job recovery, SQL schema setup, or grain lifecycle transitions. Framework guidance; do not use for operating live Chronicle jobs or for application command validation.
+license: MIT
+---
+
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Recoverable Orleans jobs
+
+For services and kernel contributors using Orleans. This is library-consumer guidance, not the application vertical-slice architecture. For live Chronicle operations use **cratis-chronicle-cli-operations** instead. Co-hosting conventions are in [orleans.md](../../rules/orleans.md).
+
+## Verified product sources
+
+All Orleans claims below are source reads from **Cratis/Orleans v1.16.3**.
+
+| Packages | Version | Sources |
+| --- | --- | --- |
+| `Cratis.Orleans`, `Cratis.Orleans.Storage` | `1.16.3` | `Source/Orleans/Jobs/{Job.cs,Job.Steps.cs,Job.Stages.cs,JobStep.cs,IJobsManager.cs,JobsOptions.cs}`; `Source/Orleans.Storage/Jobs/*` |
+| `Cratis.Orleans.Storage.MongoDB`, `Cratis.Orleans.Storage.Sql` | `1.16.3` | `Source/Orleans.Storage.MongoDB/{MongoDBJobsStorageOptions.cs,DatabaseNames.cs}`; `Source/Orleans.Storage.Sql/{SqlJobsStorage.cs,SqlJobsStorageOptions.cs,Jobs/Migrations/v1_0_0.cs}` |
+| `Cratis.Orleans.Chronicle` | `1.16.3` | `Source/Orleans.Chronicle/StateMachines/EventSourcedStateMachine.cs:19-40,77-94,128-176`; [state-machine reference](references/state-machines.md) |
+
+The API snippets cite their exact files and lines below. Product docs `Documentation/concepts/{jobs,storage-scopes,state-machines,event-sourced-state-machines}.md` supply the task vocabulary; source resolves contradictions.
+
+## 1. Choose a job, not a detached task
+
+A job plans recoverable work; each step is a grain and does the work. Use it for work that must outlive a request. It is **at-least-once**, not exactly-once: a step interrupted before a durable checkpoint can perform the same work again. Protect external effects with receiver-owned idempotency/deduplication; a checkpoint does not atomically commit an external write (`JobStep.cs:47-56`, `JobsOptions.cs:34-59`).
+
+- Job: derive `Job<TRequest, TJobState>`; the request is a class implementing `IJobRequest`, the state derives `JobState` (`Job.cs:23-25`). Implement `PrepareSteps(TRequest)` returning `Task<IImmutableList<JobStepDetails>>` (`Job.Steps.cs:63-87`).
+- Step: derive `JobStep<TRequest, TResult, TState>`; state derives `JobStepState`. Its constructor receives `[PersistentState(nameof(JobStepState), WellKnownGrainStorageProviders.JobSteps)] IPersistentState<TState>`, `IJobStepThrottle`, and `ILogger<JobStep<TRequest, TResult, TState>>` (`JobStep.cs:27-32`).
+- Implement `PrepareStep(TRequest)` → `Task<Result<PrepareJobStepError>>`; `InitializeState(TRequest)` → `ValueTask`, called after preparation succeeds; and `PerformStep(TState, CancellationToken)` → `Task<Catch<JobStepResult>>` (`JobStep.cs:350-387`). `TResult` is the step's result type; the work method returns the framework's `JobStepResult` envelope, not `TResult` directly.
+- Give the concrete job and step unique `[GrainType("product-specific-name")]` names. Use serializable request/state/result types. Do not reuse a class-derived grain name across assemblies (`Jobs/JobsManager.cs:31`, `Documentation/how-to/host-the-silo.md`, and `orleans.md`).
+
+`PerformStep` runs **outside the activation context** with a state snapshot obtained through the grain reference. Mutating that snapshot does not persist it; do not access/write grain `State` directly from background work (`JobStep.cs:375,390-450`). Keep progress/state coordination on grain calls. Since 1.16.2 the framework owns stop reporting; do not report cancellation again from a `PerformWork` override (`:390-450`, `Documentation/concepts/jobs.md:117-120`).
+
+## 2. Plan dependencies as stages
+
+Default steps all use `JobStepStage.First`. Prefer independent fan-out. Use stages only when correctness requires earlier work to finish (`Job.Stages.cs:20-44`).
+
+Planning excerpt inside an existing `Job<RecoveryRequest, RecoveryState>`. It assumes `RecoveryRequest : IJobRequest`, `RecoveryState : JobState`, and the two existing grain interfaces `IRepairIndex` and `IRebuildCatalog`, each deriving a typed `IJobStep<,,>`:
+
+```csharp
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+protected override Task<IImmutableList<JobStepDetails>> PrepareSteps(RecoveryRequest request) =>
+    Task.FromResult<IImmutableList<JobStepDetails>>(
+    [
+        CreateStep<IRepairIndex>(request, stage: 0),
+        CreateStep<IRebuildCatalog>(request, stage: 10)
+    ]);
+```
+
+Import `System.Collections.Immutable` and `Cratis.Orleans.Jobs` in that job file. `CreateStep<TStep>` takes the **grain interface**, not the implementation (`Job.Steps.cs:69-79`). Its stage overload accepts `JobStepStage`, with implicit integer conversion (`Source/Orleans.Storage/Jobs/Stages/JobStepStage.cs`).
+
+Every step in a stage reaches an outcome before later stages start; steps within a stage run in parallel. All steps are prepared up front, so later-stage preparation cannot read the effects of earlier-stage execution. Read such dependencies in `PerformStep` (`Job.Stages.cs:27-33`).
+
+A failed stage stops the pipeline by default: later steps become `Unreachable`, and the job completes with failures. A best-effort stage may override `GetFailureBehaviorFor(JobStepStage)` to return `JobStageFailureBehavior.ContinueWithNextStage` (`Job.Stages.cs:40-44,152-194`, namespace `Cratis.Orleans.Jobs.Stages`). Do not silently continue when a later stage relies on the failed output.
+
+## 3. Start and resume through the scoped manager
+
+`IGrainFactory.GetJobsManager(scope, namespace)` resolves the manager (`JobsManagerExtensions.cs:18-19`). `IJobsManager.Start<TJob,TRequest>(request)` returns `Result<JobId, StartJobError>`; inspect its error before telling a caller that a job started (`IJobsManager.cs:37-52`). Start success is not completed work; observe the job's status/outcomes.
+
+`IJobsManager.Resume(JobId)` returns **`Task<bool>`**. False means nothing took the job; do not wait for a completion callback as though resumption succeeded. True can mean resumed, already running, or finalized as completed (`IJobsManager.cs:54-64`). `Rehydrate()` completes after loading/preparing interrupted jobs, **before** its bounded background drain has resumed them all (`:15-28`).
+
+`StartStepsInBackground` defaults to false. Overriding it to true makes Start return once the job is durable, moving step preparation/start to the grain's next turn. Later startup errors belong to the job, not the Start response (`Job.cs:74-87,395-427`).
+
+## 4. Know what storage retains
+
+Successful jobs clear themselves by default; override `KeepAfterCompleted` to retain job state. Jobs completed with failures default to `KeepAfterCompletedWithFailures = true`, but retention cleanup still applies (`Job.cs:58-71`, `JobsOptions.cs:80-97`).
+
+**Keeping a job does not keep successful step state.** The step provider deletes successful/removing state, moves failed state to failed-step storage, and saves stopped/scheduled/running/unreachable state (`JobStepGrainStorageProvider.cs:64-84`). SQL keeps failed step rows with a failure status rather than a separate collection (`Source/Orleans.Storage.Sql/Jobs/JobStepStorage.cs`, `MoveToFailed`). Copy results the job must retain through `OnStepCompletedOrStopped(JobStepId, JobStepResult)` into job state (`Job.Steps.cs:49-55,110-117`); do not read deleted successful step state later.
+
+Deliver external callbacks to a method on the **job's grain interface**, update job state there and persist it with `WriteState()`. Preserve the returned `Catch` failure; do not acknowledge input whose write failed (`Job.State.cs:13-25`, `WriteState`; `Documentation/concepts/jobs.md:122-164`). Step state is not a callback inbox: a concurrent callback can race the final write, and successful completion deletes it. A running step's snapshot will not see later job/step writes automatically.
+
+## 5. Register storage and budget concurrency
+
+`IJobsStorage.GetFor(scope, namespace)` returns `JobsStorage`. Scope and namespace are opaque engine coordinates carried in grain keys; the host/provider owns their mapping (`Source/Orleans.Storage/Jobs/IJobsStorage.cs`, `Job.cs:120-125`). They are storage boundaries, not authorization checks.
+
+Choose one storage registration alongside `AddCratisOrleans`:
+
+| Registration | Package / namespace | Use |
+| --- | --- | --- |
+| `AddCratisOrleansMongoDBJobsStorage` | `.Storage.MongoDB` / `Cratis.Orleans.Setup` | Durable MongoDB; database-name resolver can override the default `{scope}+jobs[+{namespace}]` |
+| `AddCratisOrleansSqlJobsStorage` | `.Storage.Sql` / `Cratis.Orleans.Setup` | Durable EF Core; `OptionsResolver(scope, namespace)` selects typed `DbContextOptions<JobsDbContext>` |
+| `AddCratisOrleansInMemoryJobsStorage` | `.Storage` / `Cratis.Orleans.Storage` | Specs/development only; process restart loses state |
+
+Evidence: each package's `*JobsStorageServiceCollectionExtensions.cs`; MongoDB `DatabaseNames.cs` and `MongoDBJobsStorageOptions.cs`; SQL `SqlJobsStorageOptions.cs:15-27`; in-memory `InMemory/InMemoryJobsStorage.cs`.
+
+### SQL schema contradiction resolved
+
+The product's SQL setup docs say to create the schema yourself. **At v1.16.3 the provider applies migrations automatically**: `SqlJobsStorage.GetFor` calls `EnsureSchema`, which calls `dbContext.Database.Migrate()` before constructing storage (`Source/Orleans.Storage.Sql/SqlJobsStorage.cs:33-49,58-74`). The migration is `Jobs/Migrations/v1_0_0.cs`; do not substitute `EnsureCreated` or hand-create those tables. The connection needs permissions to apply the migration, and scope-to-database mapping must be deliberate. Storage is cached per scope/namespace; `IJobsStorage.Reset()` clears the cache and the next resolution migrates again (`SqlJobsStorage.cs:52-56`). This resolves the documentation conflict from source, not from a release-note inference.
+
+Configure `JobsOptions` through the host's options registration. Its properties are **init-only**: supply a constructed instance via the options mechanism rather than assigning them in a `Configure(options => options.Property = …)` callback (`JobsOptions.cs`).
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `MaxParallelSteps` | `max(1, ProcessorCount - 1)` when unset | Actual execution throttle |
+| `MaxConcurrentStepStarts` | `16` | Startup/resume calls per job, not the execution limit |
+| `MaxConcurrentRehydration` | `8` | Jobs resumed concurrently by a manager |
+| `MaxConcurrentCleanup` | `4` | Dead-job deletions |
+| `StepCheckpointBatchInterval` | `100` | Batches between durable progress checkpoints |
+| `StepCheckpointFlushInterval` | `5 seconds` | Timed checkpoint flush; nonpositive disables it |
+| `DeadJobThreshold`, `CleanupCadence` | `1 hour` each | Preparation-with-no-steps scavenging |
+| `TerminalJobRetention` | `7 days` | Terminal history retention; `Timeout.InfiniteTimeSpan` retains indefinitely |
+| `MaxTerminalJobsPerCleanup` | `100` | Bounded oldest-first cleanup page |
+
+Source: `JobsOptions.cs:17-109`. The three concurrency options for starts/rehydration/cleanup treat values below one as one. Retention does not delete preparing/running/stopped/removing jobs. Larger checkpoint intervals mean more post-crash redelivery, not higher delivery guarantees.
+
+## State machines and verification
+
+Use [state-machines.md](references/state-machines.md) for `StateMachine<TStoredState>` and `EventSourcedStateMachine<TModel>`: jobs are recoverable work, state machines are lifecycle behavior. Neither makes external effects exactly-once.
+
+Verify a new job with specs for planning, idempotent redelivery, stop/resume (including false), failed barriers/Unreachable, retention and persistence failures. Exercise the selected durable provider for restart recovery and SQL migration permissions. A build alone cannot establish crash recovery. Do not operate a live store merely to validate a code example.

package/package/corpus/skills/cratis-orleans-jobs/references/state-machines.md

@@ -0,0 +1,64 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Grain lifecycle state machines
+
+Verified from **Cratis/Orleans v1.16.3**. Use explicit states when entering/leaving a status has behavior; an enum is enough for a status with no behavior. Do not put long-running work on a grain turn just because `OnEnter` is available.
+
+## Stored lifecycle
+
+`StateMachine<TStoredState>` derives from a stateful grain. Override `InitialState` and `CreateStates()`; states derive `State<TStoredState>`. `AllowedTransitions` is an immutable list of target types, or override `CanTransitionTo<TTargetState>(storedState)` for a guard (`Source/Orleans/StateMachines/StateMachine.cs:63-67,120-192`; `State.cs:17-34`).
+
+Declaration excerpt for an existing grain file with `ProcessState : StateMachineState`, the existing `IProcess` grain interface, and a registered `processes` grain storage provider:
+
+```csharp
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+using System;
+using System.Collections.Immutable;
+using System.Threading.Tasks;
+using Cratis.Orleans.StateMachines;
+using Orleans;
+using Orleans.Providers;
+
+[GrainType("my-product-process")]
+[StorageProvider(ProviderName = "processes")]
+public class Process : StateMachine<ProcessState>, IProcess
+{
+    protected override Type InitialState => typeof(Pending);
+
+    public override IImmutableList<IState<ProcessState>> CreateStates() =>
+        [new Pending(), new Finished()];
+
+    public Task Finish() => TransitionTo<Finished>();
+}
+
+public class Pending : State<ProcessState>
+{
+    protected override IImmutableList<Type> AllowedTransitions => [typeof(Finished)];
+}
+
+public class Finished : State<ProcessState>;
+```
+
+Split types into their house-style files in the consumer; the block collects declarations to show the API. Do not copy the `processes` provider name into Chronicle's kernel; use its registered constants.
+
+A refused transition is a **no-op**, not an exception or a successful change. An unknown target throws `UnknownStateTypeInStateMachine`. The machine runs leaving hooks, `OnLeave`, entering hooks, `OnEnter`, then persistence (`StateMachine.cs:162-169,222-290`). Transitions requested while entering are scheduled; transitions while leaving throw `TransitioningDuringOnLeaveIsNotSupported`.
+
+When stored state derives `StateMachineState`, `CurrentState` stores the state's full type name; activation resolves it, enters it again, and can repeat enter effects. Renames need a stored-value migration; an unknown recorded name throws `UnknownCurrentState` (`StateMachine.cs:183-191,261-264`). A self-transition with the **same state instance** skips persistence: return a new stored-state instance when a self-transition must write (`:266-272`).
+
+For externally owned storage, the protected constructor accepts `Orleans.Core.IStorage<TStoredState>` and reads it on activation before the activation hook. Override `ResolveActivationState()` to derive lifecycle from authoritative state instead of persisting a second status (`:39-51,68-95,172-192`).
+
+## Lifecycle following Chronicle facts
+
+`EventSourcedStateMachine<TModel>` from `Cratis.Orleans.Chronicle.StateMachines` uses a Chronicle read model as authoritative state. Its interface derives `IEventSourcedStateMachine` (string-keyed). There is **no grain storage provider** to configure and writes are no-ops: `ReadModelStorage<TModel>` reads Chronicle; `ResolveState(TModel?)` derives activation state (`Source/Orleans.Chronicle/StateMachines/EventSourcedStateMachine.cs:19-40,77-94,155-176`; `ReadModelStorage.cs:68-95`).
+
+- Define states with `CreateStates()` as above, over `TModel`.
+- Define event transitions in `DefineTransitions(IStateMachineTransitions<TModel>)`, using `.On<TEvent>().When(model => predicate).TransitionTo<TState>()`. First applicable allowed transition wins. Make `ResolveState` agree with these transitions after restart (`EventSourcedStateMachine.cs:142-176`, `StateMachineTransitions.cs`).
+- Use model-bound projection attributes, an already-discovered projection, or `DefineProjection(IProjectionBuilderFor<TModel>)`, not competing projections. `DefineProjection` and `DefineTransitions` run at startup **without a constructor**: use only the builder, never injected services or fields (`EventSourcedStateMachine.cs:34-37`).
+- Register `AddEventSourcedStateMachines()` on `ISiloBuilder` or `IServiceCollection`, beside the application's Chronicle client registration; namespace `Cratis.Orleans.Chronicle.Hosting` (`Hosting/EventSourcedStateMachinesServiceCollectionExtensions.cs:30-55`).
+- Grain keys include event store, namespace and event-source ID. Use `IGrainFactory.GetEventSourcedStateMachine<TInterface>(eventStore, eventSourceId)` from `Cratis.Orleans.Chronicle.StateMachines` so tenant coordinates come from the supplied event store (`StateMachines/EventSourcedStateMachineGrainFactoryExtensions.cs:21-52`).
+- Prefer passive models. For events consumed by a materialized projection, the reactor waits for its sequence position before refreshing; `ModelCatchUpTimeout` defaults to 30 seconds and expiry fails with `ModelDidNotCatchUp` (`EventSourcedStateMachineReactor.cs:58-89`; `EventSourcedStateMachinesOptions.cs:26`).
+
+This machine **follows facts**, it does not arbitrate whether a command may append one. Keep command rejection and append-time invariants at their owning boundary. Enter/model-change effects may repeat on activation, redelivery or replay: design them idempotently (`Documentation/concepts/event-sourced-state-machines.md:240-247`). Test guards, no-op refusals, reactivation and persistence failures separately from job recovery.

package/package/corpus/skills/cratis-orleans-jobs/verification.json

@@ -0,0 +1,20 @@
+{
+  "skill": "cratis-orleans-jobs",
+  "input": "Author a staged recoverable job with SQL storage and distinguish lifecycle state machines from job execution.",
+  "fixtures": [],
+  "assertions": [
+    { "kind": "skill-contains", "value": "at-least-once" },
+    { "kind": "skill-contains", "value": "Task<Catch<JobStepResult>>" },
+    { "kind": "skill-contains", "value": "CreateStep<IRepairIndex>(request, stage: 0)" },
+    { "kind": "skill-contains", "value": "Unreachable" },
+    { "kind": "skill-contains", "value": "Task<bool>" },
+    { "kind": "skill-contains", "value": "Keeping a job does not keep successful step state" },
+    { "kind": "skill-contains", "value": "dbContext.Database.Migrate()" },
+    { "kind": "skill-contains", "value": "MaxConcurrentStepStarts" },
+    { "kind": "skill-contains", "value": "StateMachine<TStoredState>" },
+    { "kind": "skill-contains", "value": "EventSourcedStateMachine<TModel>" },
+    { "kind": "skill-contains", "file": "references/state-machines.md", "value": "A refused transition is a **no-op**" },
+    { "kind": "skill-contains", "file": "references/state-machines.md", "value": "without a constructor" },
+    { "kind": "skill-contains", "file": "references/state-machines.md", "value": "same state instance" }
+  ]
+}

package/package/corpus/skills/cratis-screenplay-discovery/SKILL.md

@@ -44,7 +44,9 @@ syntax and tool commands in `cratis-screenplay-toolchain`.
 
 Current pins are listed once in `cratis-screenplay-toolchain` `references/versions.md`. The
 statements below were checked at these older tags (Screenplay v4.66.0 `c89198b`, cratis CLI v3.28.3,
-Stage v4.24.2, Arc v22.50.5, Chronicle v19.32.0), kept as provenance, not as current pins:
+Stage v4.24.2, Arc v22.50.5, Chronicle v19.32.0), kept as provenance, not as current pins.
+Model notes use Screenplay `v4.144.0:Documentation/screenplay/model-notes.md:12-77`
+and decision 0045:40-79; tool sources: model-authoring `references/model-notes.md`.
 
 | Fact used here | Source |
 | --- | --- |
@@ -87,10 +89,12 @@ With no input at all, open with: "Describe the starting situation, then the step
 to reach the intended result." With a brief, restate domain and goal in two sentences and confirm.
 
 **Unattended: assume visibly.** Never stop to ask. Take the most reasonable assumption,
-record it with its reason in the session STATE.md (`.ai-work/screenplay/<model-slug>/STATE.md`,
-untracked) and, when it shapes the model, in the feature's fenced `documentation` (a short
-**ASSUMED** marker may stay in its `description`). Keep what the user
-decided apart from what you assumed. Never guess silently.
+record the open question and assumption as a `question` note anchored to the element,
+not chat or `description` text. STATE.md carries its note ID and assumption for handoff;
+settled reasoning belongs in `documentation`. Keep decisions apart from assumptions.
+Read [discovery questions](references/plotting-and-handoff.md#durable-discovery-questions)
+when recording or answering a question: `refs`, external decisions and realization.
+Never put secrets or personal data in note text; `.screenplay/notes.json` is committed.
 
 ## Procedure
 
@@ -209,7 +213,8 @@ and the report says which verdicts were not run (V2 to V5 are not run in discove
   Cannot lines or "none known"; every Cannot line is listed as a denial candidate.
 - Essential fields present; personal data classified on concepts.
 - Rules register, denial candidates, competition and duplicate candidates, hotspots, open
-  questions and assumptions are written in STATE.md, not only said in chat.
+  questions and assumptions are carried in STATE.md; open questions are also committed
+  `question` notes with anchors, not only said in chat.
 
 ## Verify
 

package/package/corpus/skills/cratis-screenplay-discovery/references/facilitation.md

@@ -19,8 +19,9 @@ that decision. If not, note the need as a view and move on.
 
 - When people describe the same step differently, first check whether they describe different
   situations (two branches, two roles). Often both are right.
-- If it is a real disagreement, write both versions as an open question in STATE.md, take one
-  as the working assumption (say which), and continue. Do not stall the session on it.
+- If it is a real disagreement, record both versions in an anchored `question`
+  note; carry its note ID and working assumption in STATE.md. Say which assumption
+  you use and continue. Do not stall the session on it.
 - Domain experts decide business meaning; engineers decide feasibility. When only engineers
   are present, mark business-meaning decisions as assumptions to confirm.
 
@@ -37,12 +38,15 @@ that decision. If not, note the need as a view and move on.
 
 ## Unattended runs
 
-- Never block on a question. Take the most reasonable assumption, record it in STATE.md with
-  why, and record it in feature `documentation` when it shapes the model.
+- Never block on a question during discovery. Take a visible working assumption
+  and record it with its reason in an anchored `question` note, not chat or
+  `description` text. STATE.md carries the note ID.
 - Prefer assumptions that keep the model honest (fewer, clearly named facts) over ones that
   invent detail.
 
-See "Evidence and privacy" in SKILL.md.
+Read `plotting-and-handoff.md` "Durable discovery questions" when recording or
+resolving a note with project decision `refs`. Never put secrets or personal data
+in notes. See "Evidence and privacy" in SKILL.md.
 
 ## Closing a session
 

package/package/corpus/skills/cratis-screenplay-discovery/references/human-workshop.md

@@ -80,7 +80,7 @@ No event modeling experience is needed.
 | Yellow: role | `persona` (with Does / Reads / Cannot) |
 | Blue: command (later session) | `command` (`cratis-screenplay-slice-design`) |
 | Green: view (later session) | `readmodel` and `query` (`cratis-screenplay-slice-design`) |
-| Pink: question or hotspot | an open question or hotspot in STATE.md |
+| Pink: question or hotspot | anchored `question` note (note ID in STATE.md); hotspot in STATE.md |
 
 Use the agreed colours consistently, whatever they are; the mapping is what matters.
 

package/package/corpus/skills/cratis-screenplay-discovery/references/plotting-and-handoff.md

@@ -5,6 +5,7 @@
 - 1. Sequence
 - 2. Record after / caused by / only if
 - 3. Ask what can happen instead
+- Durable discovery questions
 - 4. Plot output format
 - Whose turn is it in the story?
 - Storyline: one view walked through its states
@@ -61,6 +62,27 @@ Name every terminal state (completed, cancelled, expired, withdrawn) and every u
 correction path. Each path with a way out feeds removal specs later (an ending removes the
 thing from the views that listed it).
 
+## Durable discovery questions
+
+Every unsettled branch, dead end or assumption becomes a `question` note on the
+affected element, not chat or `description` text. Commit `.screenplay/notes.json`
+with the model. STATE.md and the plot report carry the returned note ID and
+assumption, not the only copy of the question. Before a specific element exists,
+anchor to the application or nearest identified container and name it in text.
+Never put secrets or personal data in note text, author, refs or resolutions.
+
+Read model-authoring [model notes](../../cratis-screenplay-model-authoring/references/model-notes.md)
+when recording or resolving discovery questions: `list-model-notes`,
+`propose-model-notes`, `read-proposal view=notes`, then authorized `apply`.
+A missing notes capability is a reported gap plus a note request, not a successful
+recording. For project decisions, cite `refs: [{ "id": "D123" }]`; resolve with
+`by: "external-decision"` and `ref: { "id": "D123" }` when that record answers it.
+Turn the answer into a specification, a description or a project-owned decision
+record. A resolution alone implements nothing; carry behavioral answers to slice
+design/scenario coverage. Reopen if the decision stops answering the question.
+Evidence: Screenplay `v4.144.0:Documentation/screenplay/model-notes.md:12-77`,
+`decisions/0045-model-notes-sidecar.md:40-79`; tool-source lines in the linked guide.
+
 ## 4. Plot output format
 
 Put a compact story line in the feature `documentation` and report the plot per workflow:
@@ -78,11 +100,13 @@ The plot: SeasonalBerths
 Critical path:  1 -> 2 -> 3 -> 4
 Decision points: after 1 (assign or decline); after 2 (arrive or withdraw)
 Terminal facts: BerthRequestDeclined, BoatDeparted, BerthAssignmentWithdrawn
-Wait states:    after 2, until the boat arrives (what if it never does? open question)
-Compensation:   withdrawal frees the berth for the waiting list (open question)
+Wait states:    after 2, until the boat arrives (report Q1: what if it never does?)
+Compensation:   report Q2: does withdrawal free the berth for the waiting list?
 ```
 
-For a diagram use `cratis-event-model-diagram`.
+Q1 and Q2 are report shorthand for anchored `question` notes; do not copy
+unanswered questions into the feature's `documentation`. The settled plot goes
+there. For a diagram use `cratis-event-model-diagram`.
 
 ## Whose turn is it in the story?
 
@@ -145,7 +169,7 @@ What discovery contributes:
 | Non-human causes | schedules, outside parties, own follow-up |
 | Hotspots | where it goes wrong today |
 | Set aside | non-events kept as view needs |
-| Open questions | the blocking one first |
+| Open questions | anchored note IDs and assumptions; the blocking one first |
 | Decisions and assumptions | kept apart; each assumption with its reason |
 | Verdicts | V1 result with tool and version; V2 to V5 "not run: discovery phase" |
 

package/package/corpus/skills/cratis-screenplay-discovery/references/storming-loop.md

@@ -122,6 +122,7 @@ module Moorings
         reason String
 ```
 
-Open questions that would sit in STATE.md next to it: is a declined request final or can it be
+Record anchored `question` notes for these uncertainties, carrying their note IDs
+in STATE.md: is a declined request final or can it be
 put on a waiting list; who may withdraw an assignment; must the season fee be remembered as
 set at assignment time (a decision, so a fact) or recalculated (a view)?

package/package/corpus/skills/cratis-screenplay-discovery/verification.json

@@ -4,6 +4,11 @@
   "fixtures": [],
   "assertions": [
     { "kind": "play-compiles" },
+    { "kind": "skill-contains", "value": "record the open question and assumption as a `question` note" },
+    { "kind": "skill-contains", "value": "`refs: [{ \"id\": \"D123\" }]`", "file": "references/plotting-and-handoff.md" },
+    { "kind": "skill-contains", "value": "`by: \"external-decision\"`", "file": "references/plotting-and-handoff.md" },
+    { "kind": "skill-contains", "value": "Turn the answer into a specification", "file": "references/plotting-and-handoff.md" },
+    { "kind": "skill-contains", "value": "Never put secrets or personal data", "file": "references/plotting-and-handoff.md" },
     { "kind": "skill-contains", "value": "## Interview phase" },
     { "kind": "skill-contains", "value": "Unattended: assume visibly" },
     { "kind": "skill-contains", "value": "Does / Reads / Cannot" },

package/package/corpus/skills/cratis-screenplay-model-authoring/SKILL.md

@@ -21,7 +21,8 @@ same model root or workspace export to all checks. Workflow:
 
 ## Verified product sources
 
-Screenplay v4.142.0: add/rename/remove planner in `references/property-links.md`;
+Screenplay v4.144.0: model notes sources/lines in `references/model-notes.md`;
+v4.142.0 add/rename/remove planner in `references/property-links.md`;
 compliance in command-surface `references/compliance.md`. Other MCP evidence:
 v4.139.0 `Documentation/screenplay/mcp/`.
 Discover installed tools and schemas; CLI bundles can differ from the standalone
@@ -29,9 +30,15 @@ tool. Pins are in `cratis-screenplay-toolchain` `references/versions.md`.
 Historical probes remain 4.66.0; registration example compilation/execution
 remains 4.68.0. Attribution: `references/provenance.md`.
 
+Record open modeling questions as `question` notes in committed
+`.screenplay/notes.json`, not chat or `description` text. Never put secrets or
+personal data in notes. Read [model notes](references/model-notes.md) when
+listing, recording or resolving questions: `list-model-notes`,
+`propose-model-notes`, `read-proposal view=notes`, refs and orphan review.
+
 ## Locate and connect
 
-All MCP tool calls below use the `screenplay` server declared in `.cratis/ai/mcp-servers.json`, for example `screenplay` → `open-workspace`.
+Use the declared `screenplay` MCP server (for example `open-workspace`).
 
 Never ask the user which folder to use before trying. Call `open-workspace` with no
 arguments first: a server started without a fixed root binds the folder the host or
@@ -139,7 +146,9 @@ and applies; others send an edit request ([MCP loop](references/mcp-loop.md)).
    unresolved model debt and report that debt; it does not waive structural,
    identity or binding-protection checks.
 6. Inspect `read-proposal` before/after bytes and diagnostics, including the
-   identity-state change through `workspace-state`.
+   identity-state change through `workspace-state`. Review `orphanedNotes` on
+   source proposals; reanchor or resolve affected questions before applying
+   ([notes and orphan impact](references/model-notes.md#source-proposals-can-orphan-notes)).
 7. `apply` only the reviewed server-produced proposal within the user's requested
    change. The proposal ID and before revisions are required; stale state rejects.
    When the user asked for the change to be applied ("apply it when you're done",
@@ -152,23 +161,11 @@ Node handles are revision-bound occurrences, not durable IDs. A logical module
 or feature can have multiple physical fragments. Do not edit one header and
 assume every fragment changed. After apply, fetch fresh handles/revisions.
 
-### Failures (use `failureKind`, never message text)
-
-| failureKind | Response |
-| --- | --- |
-| `StaleRevision`, `DiskDrift`, `IdentityStateDrift` | Reopen and re-propose |
-| `ProposalRejected` | Read `conflicts`; change the request |
-| `FormattingConsentRequired` | Pass `formatting` |
-| `UnknownProposal` | The connection was reopened or the proposal applied: re-propose |
-| `LimitExceeded` | Discard unused proposals (16 cap) |
-| `PendingOperation`, `RecoveryRequired` | `workspace-state`, then ask before `recover-workspace` |
-| `RootChangeRefused` | Keep the fixed root, or start a new connection |
-| `ApplyOutcomeUnknown`, or EOF during `apply` | **Never retry `apply`.** Reconnect, read `workspace-state`, ask the user |
-
-Never delete `.screenplay/pending.json`. Limits reject and never truncate: 512
-files, 8 MiB total, 2 MiB per file, 1 MiB structured result, 200 items or 192 KiB
-per page. Excluded directories: `.git`, `.ai-work`, `.screenplay`, `bin`, `obj`,
-`node_modules`.
+Read [failures and limits](references/mcp-loop.md#failures-use-failurekind-never-message-text)
+when a call refuses or paging hits a limit; use `failureKind`, never message text.
+After revision/disk/identity drift, reopen and re-propose. For `ApplyOutcomeUnknown`
+or EOF during `apply`, **never retry apply**: reconnect, inspect `workspace-state`
+and ask. Never delete `.screenplay/pending.json`. Limits reject, never truncate.
 
 Choose formatting explicitly and disclose dropped comments before applying;
 read [formatting and limits](references/mcp-loop.md#formatting-and-limits) for
@@ -267,13 +264,11 @@ retry the same input.
 
 ## Code attachments
 
-Policy, validation-rule, reducer, handler, performer and reaction bodies, and
-`file` constraints, are opaque code the model points at.
-Screenplay never compiles or runs them. A `screen`'s `file` is a UI realization file, not an attachment.
-`read-workspace` or `read-proposal` with `view: "implementation-requirements"`
-lists each attachment with a content hash and source map; a hash is not evidence
-that the code compiles or behaves. Read `references/mcp-tools.md#code-attachments` when resolving an attachment or diagnosing attachment warnings. Path resolution and `PLAY0430`-`PLAY0434`:
-[MCP tool guide](references/mcp-tools.md#code-attachments).
+Code bodies and `file` constraints are opaque attachments. Screenplay never compiles or runs them.
+A screen's `file` realizes UI, not an attachment. Read
+[MCP code attachments](references/mcp-tools.md#code-attachments) when resolving
+paths or diagnosing `PLAY0430`-`PLAY0434`; `read-workspace`/`read-proposal`
+`view: "implementation-requirements"` hashes/maps are not behavioral evidence.
 
 ## Verify and report honestly
 
@@ -306,8 +301,7 @@ Record screen MCP transcripts in `.ai-work/`; render/runtime checks must use the
 same source, never an app that silently drops authored UI. Use the Screenplay-owned canonical
 corpus fixture path instead of copying available `.play` fixtures here.
 
-Check installed `tools/list` schemas: the CLI bundle can differ. Never invent
-commands, parameters, syntax nodes or downstream capabilities.
+Never invent commands, parameters, syntax nodes or downstream capabilities.
 
 ## Route near misses