@cratis/pi 7.112.0 → 7.114.0

package/package/corpus/skills/cratis-orleans-jobs/references/lifecycle-and-placement.md

@@ -0,0 +1,52 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Lifecycle, recovery and placement
+
+## Stop, drain and admission
+
+Requires Cratis.Orleans 1.20.0 for `IJobs.StopAndDrain(key, jobId, timeout)` and the grain protocols `IJobDrain` / `IJobStepDrain`. Unlike ordinary stop acceptance, `Drained` means no step code can run, final outcomes/checkpoints are durable and completion/stop hooks finished. Other outcomes are `TimedOut` (call again), `Completed`, `NotFound` and `UnknownJobType`. `TimeSpan.Zero` polls. Add the method to hand-written `IJobs` implementations. Enable only after every silo supports it. A pending drain survives reactivation and refuses resume; a timeout is not proof of quiescence. Hooks can repeat or be missed after a crash, so keep them idempotent rather than collecting results only there.
+
+Requires 1.21.0 for owner admission: implement `IJobAdmission.MayRun(JobAdmissionRequest, CancellationToken)` and register with `siloBuilder.AddJobAdmission<T>()` on every silo that hosts those job types. Every admission must allow; none means allow. It runs before start, every resume and each later stage. Refusals return `StartJobError.NotAdmitted` / `CannotResumeJobError.NotAdmitted`; manager resume returns false. A refused running job is stopped/drained, and a refused later stage stops the job. Exceptions/timeouts are failures, not refusals; a later stage retries an unanswered admission on a timer.
+
+`MayRun` runs in the job's turn: never call the job, its steps, or a non-interleaving grain that could be waiting on this start/resume. To change what existing work may do, the owner calls `StopAndDrain` **before** changing the admission answer. Older silos do not ask, so admission guarantees require every silo to run the supporting version. Admission does not by itself serialize arbitrary host-owned mutual-exclusion rules.
+
+## Bounded delivery and retries
+
+Requires 1.23.0 for these opt-in execution controls. Defaults preserve unbounded dispatch, one execution attempt and no lease timeout:
+
+| Option | Default / meaning |
+| --- | --- |
+| `MaxActiveStepsPerJob` | `null` (all); a positive limit fills a dispatch window within a stage |
+| `MaxStepAttempts` | `1`, including first attempt; failed work can retry when increased |
+| `StepRetryBackoff`, `MaxStepRetryBackoff` | `5 seconds`, `5 minutes`; capped exponential delay |
+| `JobWatchdogInterval` | `1 minute`; probes stalled delivery/progress |
+| `StepLeaseTimeout` | `TimeSpan.Zero` disables heartbeat lease enforcement |
+| `StepDeliveryMaxAttempts` | `10` |
+| `StepDeliveryRetryDelay`, `MaxStepDeliveryRetryDelay` | `1 second`, `30 seconds` |
+
+The watchdog restarts a leased step only after its owner silo left the cluster **and** its lease expired. Steps saved by older releases get one lease period. `Job.ShouldRetryStep` decides which failures retry, and `Job.MaxActiveSteps` can override the window. Persist optional `Attempt` and `Lease` on custom step state; old records default to attempt 1 and no lease. `IJobStepStorage.CountByStatus(jobId)` has a default implementation. A step persists its terminal state before retrying outcome delivery; exhausted delivery does not turn that completed step into a new failed execution. The watchdog reconciles stored outcomes if reports never arrive. Keep work idempotent: leases and delivery deduplication do not make external effects exactly-once.
+
+`IJobsManager.RetryFailedSteps(jobId)` is opt-in through `Job.CanRetryFailedSteps` and runs failed steps of a job completed with failures again. Ordinary resume is unchanged. It is not a general rerun of a successful job.
+
+## Step test runs
+
+Requires 1.22.0 for `step.BeginTestRun()` and `JobStepTestRun<TState>.Perform(state)` in a specification host. `Perform` runs `PerformStep` off activation with the supplied state and returns its `Catch<JobStepResult>`; `TryInvokeOnActivation` callbacks run serially on a stand-in scheduler. `IsOnActivation` tests that state changes happen in callbacks. `Stop()` cancels work while admission remains open; `CloseAdmission()` refuses callbacks. A run performs once and records/delivers nothing to a job. Cover `JobStepAlreadyHasALiveRun` and `JobStepTestRunWasSuperseded` misuse. This does not isolate external effects: use safe substitutes, not a live job/store.
+
+## Custom storage and rolling upgrades
+
+Persist the complete `JobState`, including `StopFinalized`, `StoppedStepsCounted` and `CompletedStepsCounted`. Missing lists read as empty for old records; do not project these fields away when storing state. The completion list tracks outcomes in executions begun by resume/retry, not jobs never resumed, and warns at 100,000 entries. Cross-version code that does not persist the list can lose duplicate protection, so keep mixed-version windows short.
+
+A completed stop sets `StopFinalized` after all required notifications have succeeded. Unfinalized stops are retried; finalized stops are excluded from recovery through `IJobStorage.GetJobsExcludingFinalizedStops`. Custom providers can override its default in-memory filtering to filter in storage. MongoDB and SQL filter there; MongoDB adds `status_stopFinalized`. SQLite, PostgreSQL and SQL Server jobs storage are supported; MySQL/MariaDB is not. Removing jobs likewise retries unacknowledged notifications; acceptance of removal is not quiescence or immediate physical deletion.
+
+## Independent controller and worker placement
+
+Requires 1.30.0 for `Cratis.Orleans.Hosting` extensions on `ISiloBuilder`:
+
+- `AddJobPlacement()` or `AddJobPlacement<TDirector>()` opts controllers into `JobsPlacementStrategy`.
+- `AddJobStepPlacement()` or `AddJobStepPlacement<TDirector>()` opts workers into `JobStepsPlacementStrategy`, including recovered steps.
+- Directors implement Orleans `IPlacementDirector`. Host directors decide eligibility; throw `NoEligibleJobWorker` when no silo is eligible. Orleans does not retry that exception; the job's failure handling applies.
+- Without an opt-in, controller placement remains resource-optimized and workers use the cluster default. The built-in directors preserve those defaults when an opt-in has no custom director.
+- **Wait until every silo runs the supporting version**, then register each strategy identically on every silo. Do not introduce the strategy during a mixed-version rollout.
+
+`UseJobStepParallelismFromSiloMetadata()` independently sizes each silo's throttle from the positive integer `cratis.jobs.max-parallel-steps` metadata value (or the supplied metadata key). Missing, nonnumeric or nonpositive values fall back to `JobsOptions.MaxParallelSteps` and its processor-count default. Publish with Orleans `UseSiloMetadata`. This is a startup value, not live resizing, authorization or admission. Keep controller placement, worker eligibility, execution throttling and job admission as separate choices.

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

@@ -44,7 +44,9 @@ 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`). Transitions requested while entering are scheduled; transitions while leaving throw `TransitioningDuringOnLeaveIsNotSupported`.
+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`).
+
+Requires 1.22.3 for transitions admitted during entry to queue FIFO rather than be dropped. Their request tasks complete on admission, **before** the queued transition executes. If another state has been entered, the target is rechecked and silently skipped when refused; a failed drain discards pending targets and fails its owning task. Transitions while leaving still 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`). A self-transition with the **same state instance** skips persistence: return a new stored-state instance when a self-transition must write.
 

package/package/corpus/skills/cratis-release-notes/SKILL.md

@@ -111,6 +111,29 @@ Only when asked to fix a release that violates the contract:
    only when the request covers closing issues; otherwise list the issues as a
    proposal. Leave an issue open when the release only partly delivered it.
 
+## Release-action batching and recovery
+
+Requires release-action 1.5.1 for corrected pending-major hotfix handling; check the workflow's `uses` pin, or keep immediate releases on the older contract.
+
+`release-window` defaults to `0` (one
+release per PR); a positive minute window batches pending merges once the oldest
+is old enough. The highest intent wins, notes merge by section with one combined
+`## Summary`, and delivered `(#n)` issues still close. Reference definitions are
+preserved; duplicate labels keep the first definition and warn. Missing intent
+labels warn but are not permission to omit required PR labels.
+
+`hotfix-labels` defaults to `hotfix` and bypasses the window. With a pending major,
+only the merge run for the hotfix fails; scheduled/other merge runs warn and leave
+the batch pending. A manual run without a version releases everything pending;
+obtain the required human major confirmation first. Inspect `pull-requests` and
+`reason` (`batched` or `nothing-pending`) rather than assuming every successful
+run released. Never turn on batching just to clear a queue without authorization.
+
+A release-creation 403 caused by workflow drift names the recovery:
+dispatch the publish workflow from the current default branch with the PR's
+release notes. Re-running the stale commit does not fix this. Other 403s keep
+their original cause; do not treat every permission failure as workflow drift.
+
 ## Verify before handing over
 
 1. Reconcile every version, affected range, capability and API against the

package/package/corpus/skills/cratis-screenplay-command-surface/references/protected-reads.md

@@ -117,8 +117,9 @@ which is one more reason to keep refused shapes out of read keys.
 
 Decide records the unfiltered fact-log boundary, read key and handled event types.
 A matching fact after that boundary makes commit return Conflict /
-DecisionStateChanged with no command facts, including publications. Irrelevant
-facts do not conflict and remain in the committed world. Even a no-fact command is
+DecisionStateChanged with no command facts, including publications. Append constraints
+are checked first: if the same candidate violates a constraint and a protected read,
+the constraint rejection wins. Irrelevant facts do not conflict and remain in the committed world. Even a no-fact command is
 checked. Race cases are evaluator vectors, not a new `.play` specification construct.
 
 Specify present/absent state, rule refusal and denial. Assert no new facts and

package/package/corpus/skills/cratis-screenplay-legacy-extraction/references/prologue-safety.md

@@ -151,6 +151,20 @@ Record in the evidence table: who ran which statements, when, and the verificati
 summary.
 
 ## 5. Capture verification before interpreting
+
+Requires Prologue 2.0.5 for the emission/image behavior below; check pinned package/image versions and `cratis --version` against its bundle, or upgrade before relying on it.
+
+Upgrade older Extractor installations for the PKCS denial-of-service dependency
+fixes. Extractor, Interpreter and Receiver images support linux/amd64 and
+linux/arm64; Apple Silicon does not need a forced amd64 platform.
+
+Heuristics-only interpretation retains each command's own correlated events
+when routes merge, declares shared events once, treats insert-plus-update in one
+transaction as creation, omits text-only `not empty` rules for required numbers
+and declares/key-identifies referenced read models. Do not retain manual
+workarounds for old emitter defects. These repairs do not prove intent or compile
+the output for you: still run executable validation on the emitted model, not
+only parsing, and record remaining diagnostics.
 - Capture files exist for every enabled source.
 - Commands per route match the scenario script; status-code mix matches expected rejections.
 - Fraction of DB transactions correlated to a command (low: concurrency or jobs).

package/package/corpus/skills/cratis-screenplay-toolchain/references/screenplay-contract.version

@@ -1 +1 @@
-4.244.0
+4.245.0

package/package/corpus/skills/cratis-specifications-csharp/SKILL.md

@@ -44,6 +44,17 @@ Requires `Cratis.Arc.Testing` 22.67.0 for generated-value scenario pinning.
 Check the owning product repository before claiming support for
 another version. Never translate an assertion or helper name from memory.
 
+Requires Specifications 4.4.0 for Given/When lifecycle aliases across framework packages; check `dotnet list package`, or keep Establish/Because on older packages.
+
+`Given`/`When` are lifecycle aliases, but house style remains `Establish`/`Because`;
+declaring both forms of a phase produces CRSPEC0009. Inherited phases execute
+once and preserve the original exception; `ValueTask` is awaited. The native
+runner remains experimental: CRSPEC0010 rejects `async void`, CRSPEC0011 warns
+about trim/AOT-unsafe reflective lifecycle calls. Shared resources/leases, phase
+timings, runtime defaults and parallel NUnit fixtures are opt-ins, not blanket
+recommendations to parallelize a stateful suite. Read the product upgrade guide
+before changing runner or package family.
+
 ## Route near misses
 
 - The specification is TypeScript, React, or a view model: use
@@ -202,8 +213,9 @@ public class when_<behavior> : Specification
   leave no blank line between `should_` methods.
 - Fields are `private` in a concrete specification and `protected` in a `given/`
   context, named `_camelCase`.
-- Any phase may be `async Task`. `void Destroy()` is optional teardown, after
-  once per eligible class by default (shared lifecycle); after each fact in a
+- Any phase may return `Task` or `ValueTask`; both are awaited. Never use `async void`.
+  `void Destroy()` is optional teardown, once per eligible class by default
+  (shared lifecycle); after each fact in a
   `[PerFactSpecificationLifecycle]` class.
 
 `Cratis.Specifications.XUnit.v3` discovers `Establish`, `Because`, and `Destroy` by

package/package/corpus/skills/cratis-specifications-csharp/references/running-specs.md

@@ -82,7 +82,14 @@ and record the spec count and outcomes first.
    Specifications.
 5. Fix each `CRSPEC0008` error by moving the change into `Establish` or `Because`; use
    `[PerFactSpecificationLifecycle]` only when the fact genuinely needs a fresh instance.
-6. Rebuild with warnings as errors and fix new nullable warnings.
+6. Change assertion delegates typed as `Predicate<T>` to `Func<T, bool>`; for
+   NUnit 4 comparisons that relied on unordered `ShouldEqual(params)`, use
+   `ShouldEqualInAnyOrder`. Null actual values now fail, including nullable
+   `ShouldNotContain` strings. Assertions live in core with forwarded types;
+   rebuild with warnings as errors and fix new nullable warnings. Delete
+   `CratisSpecificationsWarnOnSharedContextMutation` (it has no effect in 5).
+   Native-runner `async void` facts/phases must return `Task` or `ValueTask`
+   instead (CRSPEC0010 is an error).
 7. Run the executable and require the same total, the same passed count and the same
    classes and methods as the baseline (display names may become more readable),
    with no new skips. A different count means a spec was

package/package/corpus/skills/cratis-specifications-csharp/references/shared-lifecycle.md

@@ -32,18 +32,35 @@ implementations, custom fact test cases and plain xUnit classes keep the per-fac
 
 Requires Cratis.Specifications 4.4.0 or later for `IDisposable` specifications to share
 the lifecycle; earlier versions use per-fact construction. With shared lifecycle enabled,
-construction happens once and `Dispose` runs once after the last fact. Use
+construction happens once, and `Destroy` runs followed by
+one `Dispose` after the last fact, even when `Destroy` fails. Class/collection fixtures remain owned by xUnit,
+with assembly fixtures also supported on v3. Use
 `[PerFactSpecificationLifecycle]` when a fresh instance per fact is needed.
 
 `Specification.InitializeAsync()` is idempotent for a single instance. It does not make
 an ineligible class shared or cache instances across classes.
 
+## Native runner teardown outcomes
+
+Requires Cratis.Specifications.Runner 5.0.3 for separate class teardown results; check `dotnet list package`, or expect the older runner to mark every fact failed after teardown fails.
+
+A failing `Destroy`, disposal or scope end produces one separate failed result
+for the specification class and fails the run. Completed facts keep their own
+outcomes, as on xUnit/NUnit. Select the teardown result to rerun its class; passing
+facts do not imply the class or run passed.
+
 ## CRSPEC0008
 
 `CRSPEC0008` is an error by default: a `should_` fact that assigns to or increments an
 instance field or property of the specification, or calls `Add`, `AddRange`, `Remove`,
 `RemoveAt`, `Clear` or `Insert` on one, would make the result depend on fact order.
-Move the change into `Establish` or `Because`:
+Requires Specifications 5.0.2 for Received.InOrder verification recognition; check `dotnet list package`, or upgrade before relying on this diagnostic exception.
+
+Calls inside NSubstitute `Received.InOrder(...)` delegates are recognized as
+verification, but assignments and increments there still mutate state and are
+reported. Theories, per-fact classes/assemblies, immutable collection calls and
+collection calls whose return value is used are excluded. Move actual mutations
+into `Establish` or `Because`:
 
 ```csharp
 public class when_registering : Specification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "7.112.0",
+  "version": "7.114.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [