@cratis/pi 7.112.0 → 7.114.0

package/package/corpus/skills/cratis-chronicle-cli-operations/references/recovery-and-comparison.md

@@ -0,0 +1,68 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Recovery outcomes and namespace comparison
+
+Check the installed `cratis llm-context` and server version before using these
+commands. Confirm server, event store, namespace and exact targets. A prompt or
+`--yes` is not authority to mutate a live store.
+
+## Jobs: acceptance is not completed removal
+
+Requires CLI 3.79.0 for `chronicle jobs stop` / `resume` and the terminal
+Workbench to report kernel refusals as failures, with reasons in text/JSON and a
+nonzero exit. Do not parse an old CLI's success message as proof of progress.
+Inspect the job again; resume can be refused for missing, concluded, unpersisted
+or otherwise unresumable work. Do not repeat it without understanding the reason.
+
+Requires CLI 3.99.0 for `cratis chronicle jobs delete <JOB_ID>`. It is destructive
+and irreversible: retained job state is removed. Before confirmation it names
+the store, namespace and job id. An invalid GUID, declined/unavailable prompt,
+server refusal, authorization failure or server error is nonzero. `--yes` skips
+only the local prompt; the server still authorizes and decides. Exit zero and
+"deletion requested" are **not** proof of completed removal. Capture the relevant
+pre-state first and inspect again after an authorized deletion. This is not a
+terminal Workbench key or permission to delete every retained job.
+
+## Retry all failed partitions
+
+Requires CLI 3.79.0 and Chronicle 19.80.0 for
+`cratis chronicle observers retry-failed-partitions <OBSERVER_ID>`. It starts
+server-owned bounded-batch recovery and reports how many partitions were failed;
+it does not wait for all handlers to succeed. Inspect failures first, fix their
+cause, authorize the observer-wide target, then re-read state after the request.
+Do not mistake this for a client loop of one-partition requests or a guarantee
+that quarantines were cleared.
+
+## Inspect or repair a closed scope
+
+Requires CLI 3.80.0 and Chronicle 19.39.0 for
+`cratis chronicle streams closed list`. It is read-only and lists exact scope
+dimensions, origin, owner constraint, sequence number and closing time. Filter by
+event source id/type and event stream type/id; do not select a repair from a
+partial dimension match.
+
+`cratis chronicle streams closed reopen --reason <text>` is a confirmed,
+mutating repair of **one exact** mistaken manual close. Supply the scope flags
+shown by the installed help/catalog and the reason. The kernel records actor
+and reason in `StreamScopeReopened` and refuses a closure owned by a closing
+event. `--yes` skips confirmation, not that ownership check. Never turn this into
+a way around a modeled closure or reopen broad scopes speculatively.
+
+## Compare a model with live metadata
+
+Requires CLI 3.85.0 for
+`cratis screenplay conform-namespace <model> --event-store <store> --namespace <ns>`.
+This is a read-only comparison, not model authoring, rendering or state repair.
+It compares registered event types, producing commands/reactors and observers
+with the model, scanning metadata up to the tail captured at start. The default
+`--max-events` is `100000`; `--from`/`--to` bound a range. A partial scan stays
+partial; without `--fail-on-drift` a drift report need not fail the command.
+
+Requires 3.89.1 for authorization failures to exit 4 (`authentication_error`),
+Ctrl+C between pages to exit 8 (`inconclusive`), and event attribution only when
+the causation is a command. Chronicle's metadata API still transmits event source
+ids and subjects; the CLI drops them without persisting them. Do not claim they
+never cross the connection. It does not request payloads or command values.
+Redact the report before sharing it, and do not treat an incomplete or cancelled
+comparison as evidence of conformance.

package/package/corpus/skills/cratis-chronicle-client-elixir/SKILL.md

@@ -103,6 +103,12 @@ channel exists return `{:error, :not_connected}`.
 
 ## Authentication and TLS
 
+Requires Chronicle.Elixir 3.14.1 for client crash-report redaction; check `mix deps`, or treat older crash reports as potentially secret-bearing and upgrade before sharing them.
+
+The client Logger filter redacts authentication secrets and gRPC/Mint request-header
+state from crash reports; no application-level filter is needed for those client
+reports. This does not authorize logging credentials in your own code.
+
 Use `ConnectionString.development()` locally: `default()` supplies **no
 credentials**, so an authentication-required development kernel never lets it
 reach `:registered`. Production uses URL userinfo `client-id:secret@host` or
@@ -196,6 +202,12 @@ failure.
 
 ### Reactors
 
+Requires Chronicle.Elixir 3.14.0, contracts 19.70 and kernel 19.70.0 for start_at_tail; check `mix deps` and the server version, or retain initial catch-up until upgraded.
+
+`use Chronicle.Reactors.Reactor, start_at_tail: true` skips history only on first
+registration; an existing reactor keeps its position. `once_only` does not skip
+initial catch-up. An older server ignores the flag and catches up from the beginning.
+
 Read [references/reactor-example.md](references/reactor-example.md) when you need a worked reactor module.
 
 - **`@handles` is an accumulating module attribute** declaring the subscription;

package/package/corpus/skills/cratis-chronicle-client-elixir/references/decision-reads.md

@@ -3,6 +3,16 @@
 
 # Decision reads and the dynamic consistency boundary
 
+Requires Chronicle.Elixir 3.14.2 for the rejection/cleanup behavior below; check `mix deps`, or upgrade before relying on a rejected callback to discard buffered events.
+
+A `Chronicle.decide/2` callback returning `{:error, reason}` rejects all buffered
+appends and returns that tuple unchanged.
+Migrate matches on `{:ok, {:error, _}}` to `{:error, _}`. A failed commit rolls
+back the unit of work, and both `decide/2` and `with_unit_of_work/2` stop their
+unit-of-work process on return, so later appends from long-lived GenServers or
+Phoenix connections are not trapped in a failed buffer. Spec the rejection and
+failed-commit paths, not only successful decisions.
+
 Source: `Cratis/Chronicle.Elixir`: `Source/chronicle/lib/chronicle/read_models/decision_reads.ex`, `decision_read_refused.ex`, `decision_conflict.ex`, `transactions/unit_of_work.ex`, and `Documentation/dynamic-consistency-boundary.md`.
 
 Requires `cratis_chronicle` 3.13.0.

package/package/corpus/skills/cratis-chronicle-client-go/SKILL.md

@@ -128,7 +128,15 @@ identity. `delivery.ID()` can key an external idempotency record; it is not an
 exactly-once guarantee. Return supported follow-up events rather than manually
 recreating effect dispatch; use projections for materialization, reactors for effects.
 
-`reactors.OnceOnly` excludes replay; it does **not** deduplicate failed-partition
+Requires Chronicle.Go 0.11.0 and kernel 19.70.0 for StartAtTail; check `go list -m github.com/Cratis/Chronicle.Go` and the server version, or retain catch-up behavior until both are upgraded.
+
+Opt into `reactors.StartAtTail()` for a new side-effect reactor that must skip
+history. It only changes first registration: existing positions are retained and
+explicit replay still starts at the beginning. Older kernels ignore this option
+and catch up history. `observation.Service.FastForward` and `FastForwardResult`
+move an observer to the tail; this deliberate administrative skip is not recovery.
+
+`reactors.OnceOnly()` excludes replay; it does **not** deduplicate failed-partition
 recovery. Effects may repeat after errors, cleanup failures or reconnect. Keep them
 idempotent. The kernel owns recovery/quarantine and progress; do not invent resume
 positions or acknowledge before successful processing and cleanup. Read the
@@ -137,7 +145,9 @@ for exact effect, replay and registration-readiness limits.
 
 ## Unsupported does not mean success
 
-Requires Chronicle kernel 19.32.3 for decision guards, with compatibility preflight;
+Requires Chronicle kernel 19.70.0 for the current Go decision-guard profile; check the server version or postpone the client upgrade.
+
+Decision guards include compatibility preflight;
 unsupported kernels return `ErrUnsupported`. Protected operations have their own
 kernel capability gates; the client supports qualified protected revisions and
 classified read-model replay routes, not every protected watch/profile.

package/package/corpus/skills/cratis-chronicle-client-kotlin/SKILL.md

@@ -11,6 +11,10 @@ ordinary JVM application that happens to talk to a Chronicle server over gRPC.
 There is no framework to inherit from and no application architecture imposed:
 you construct a client, ask it for an event store, and append or observe.
 
+For Chronicle.Kotlin 7.x, first read the
+[Fundamentals migration and upgrade notes](references/fundamentals-migration.md):
+`ConceptAs.value()` and the shared correlation type are breaking changes.
+
 ## Verified product sources
 
 Source: `Cratis/Chronicle.Kotlin`, by source symbols and signatures.

package/package/corpus/skills/cratis-chronicle-client-kotlin/references/annotations-and-handlers.md

@@ -13,7 +13,12 @@ This reference holds the observer annotations, their arguments, filtering annota
 | `@Constraint` | `id = ""` | `constraints/Constraint.kt` |
 | `@Seeder` | none | `seeding/Seeder.kt` |
 
-Handler-level: `@Replay`, `@OnceOnly`. Observer filtering: `@Tag`/`@Tags`,
+Requires Chronicle.Kotlin 6.15.0 and kernel 19.70.0 for StartAtTail; check Gradle dependencies and the server version, or retain initial catch-up.
+
+`@StartAtTail` on a reactor class skips initial history only. Existing positions
+are unchanged.
+`@OnceOnly` targets both classes and functions: it skips replay, not initial
+catch-up or redelivery. Handler-level replay override: `@Replay`. Observer filtering: `@Tag`/`@Tags`,
 `@FilterEventsByTag`/`@FilterEventsByTags`, `@EventSequence`,
 `@EventSourceType`, `@EventStreamType`.
 

package/package/corpus/skills/cratis-chronicle-client-kotlin/references/fundamentals-migration.md

@@ -0,0 +1,48 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Shared concepts, correlation and observer upgrades
+
+## Shared concepts and correlation
+
+Requires Chronicle.Kotlin 7.0.0 for the shared concept and correlation type migration below; check Gradle dependencies, or retain the earlier client API until deliberately migrating and recompiling.
+
+Import `ConceptAs` from `io.cratis.fundamentals.concepts` and implement `value()`,
+not a property/getter. Java record accessors satisfy this interface directly.
+Import `CorrelationId` from `io.cratis.fundamentals.execution`, use `NOT_SET` and
+`value()`, and recompile consumers. The old Chronicle names are warning-level
+Kotlin typealiases for this major version, not a permanent alternative API.
+Typed source-id overloads consume Fundamentals concepts. Follow the product's
+[migration guide](https://github.com/Cratis/Chronicle.Kotlin/blob/main/Documentation/guides/migrate-to-fundamentals.md).
+
+Requires Chronicle.Kotlin 7.1.0 and Fundamentals 0.6.0 for shared ambient correlation context; check Gradle dependencies, or pass correlation explicitly instead of relying on shared ambient state.
+
+The module-level `correlationIdManager` delegates to Fundamentals' shared
+`CorrelationIdContext`. Its own API still takes/returns UUIDs; separately
+constructed managers remain independent. State is thread-bound, not
+coroutine-bound: pass correlation explicitly for suspending/thread-hopping work
+and clear ambient context at the boundary. Never assume a pooled thread is a
+request or tenant scope.
+
+Event/read-model enum values are written as ordinal numbers to match their
+schemas. Stored names remain readable; undefined ordinals, including numeric
+strings, are rejected. Do not rearrange persisted enum ordinals casually.
+
+## Observer and transport upgrades
+
+Requires contracts and kernel 19.70.0 for StartAtTail; check the server version, or retain initial catch-up until it is upgraded.
+
+`@StartAtTail` applies to reactor classes in Kotlin and Java. It skips history
+only on first registration; existing positions remain. `@OnceOnly` excludes
+replay, not initial catch-up or redelivery. Older servers ignore the tail flag.
+
+Requires Chronicle.Kotlin 6.14.0 and kernel 19.56.0 for fastForward; check Gradle dependencies and the server version, or do not offer this administrative operation.
+
+`store.observers.fastForward(...)` accepts an identifier or reactor/reducer class
+and returns `FastForwardResult`, with a Java bridge. It deliberately skips work;
+it is not recovery or deduplication.
+
+`ChronicleOptions.maxReceiveMessageSize` and `withMaxReceiveMessageSize()` default
+to 100 MB; `null` retains grpc-java's own default. The constructor and `copy()`
+have a trailing parameter; earlier constructor overloads remain. Recompile affected
+calls rather than treating transport capacity as a query bound.

package/package/corpus/skills/cratis-chronicle-client-typescript/SKILL.md

@@ -186,6 +186,24 @@ before enrollment.
 
 ## Observing
 
+Requires Chronicle.TypeScript 6.53.0 and kernel 19.70.0 for startAtTail; check `yarn why @cratis/chronicle` and the server version, or retain catch-up until both are upgraded.
+
+`@startAtTail()` skips history only on first registration; existing positions
+stay intact. `@onceOnly()` does not skip initial catch-up. Older servers ignore
+the new flag.
+
+Requires Chronicle.TypeScript 6.52.0 and kernel 19.56.0 for fastForward; check the client/server versions, or do not offer the operation.
+
+`observers.fastForward(observerId)` returns `FastForwardResult`; it deliberately
+skips to the tail, not a retry mechanism.
+
+Requires Chronicle.TypeScript 6.53.1, kernel 19.78.1 and Fundamentals 7.24.1 for the child/default-value behavior below; check installed packages and server version, or upgrade before relying on it.
+
+Child/nested `@fromAllEvents` and `@fromEvery` keep root-only mappings off new
+children. Replay affected projections to rebuild already-materialized child
+values. Unset read-model fields retain their class defaults; absent arrays stay
+empty.
+
 ### Handlers use camelCase names or `@handles(EventType)`
 
 The default is the camelCase event class name, **not** parameter-type dispatch.

package/package/corpus/skills/cratis-chronicle-client-typescript/references/lifecycle.md

@@ -1,5 +1,12 @@
 # Connection lifecycle
 
+Requires Chronicle.TypeScript 6.51.1 for message-size options; check `yarn why @cratis/chronicle`, or keep gRPC defaults until upgrading.
+
+`ChronicleOptions` and its factory methods accept `maxReceiveMessageSize` and
+`maxSendMessageSize`. Both default to 100 MB; pass `null` to keep gRPC's own
+default. Check payload bounds before increasing limits; a transport allowance is
+not an unbounded-query policy.
+
 This reference holds the watchdog, reconnect, keepalive, compatibility check and telemetry behavior.
 
 ## Lifecycle

package/package/corpus/skills/cratis-chronicle-read-model/references/queries.md

@@ -32,9 +32,11 @@ Chronicle extensions — Chronicle declares no `Observe` on `IMongoCollection<T>
 
 ## Discovery rules
 
-Arc discovers eligible **public and internal static** methods on `[ReadModel]`
-types. Internal visibility is not an endpoint privacy boundary. Keep helpers
-outside the read model, regardless of their visibility. Use
+Arc discovers eligible **public static** methods on `[ReadModel]` types.
+Requires Arc 22.121.0: non-public methods are excluded even with `[Query]`, and
+ARC0029 warns on a non-public query-shaped method. A public query on an internal
+read-model type still works. On older Arc, internal statics are exposed too;
+keep helpers outside the read model when supporting those versions. Use
 `[ReadModel(RequireQueryAttribute = true)]` and `[Query]` on intended endpoints
 when the type also has folds (`Create`/`Reduce`); `[Query]` alone does not hide
 siblings. Requires Arc 22.27.1 for exclusion of private, protected, special-name

package/package/corpus/skills/cratis-cli-terminal-workbench/SKILL.md

@@ -138,7 +138,11 @@ Several views bind a key to an operation that changes the running server:
 | Jobs | `S` / `U` | stop / resume the job |
 | Recommendations | `A` / `I` | perform / ignore the recommendation |
 
-Each has a bulk form that applies to every checked row.
+Each has a bulk form that applies to every checked row. Requires CLI 3.79.0 for
+job stop/resume to display kernel refusals as failures rather than success.
+Inspect the reason and re-read the job; acknowledgement is not completed work.
+Retained-job deletion is a separate CLI command (3.99.0), not a Workbench key;
+read **cratis-chronicle-cli-operations** before requesting it.
 
 Every one of these opens a centered confirmation modal that states the action
 cannot be undone. **Only an explicit `Y` (or the Confirm button) confirms;

package/package/corpus/skills/cratis-components-common-controls/SKILL.md

@@ -20,6 +20,17 @@ All claims and prop shapes are from **Cratis/Components** source rather than unc
 
 Imports are exported by `Source/Common/index.ts`; `Source/package.json` exposes the `Common` subpath. Use **cratis-components-styling** for the provider and CSS setup and **cratis-components-accessibility** for naming/focus. These controls do not replace Arc's generated `InputTextField`/other command fields; use **cratis-arc-react-page** for those bindings.
 
+Requires Components 4.38.0 for provider routing and forwarded non-modal calendar fields; check `yarn why @cratis/components`, or retain host navigation and modal dates.
+
+Set `CratisComponentsProvider.router` with `navigate` and optional `useHref` to
+integrate `Breadcrumbs` and other link components with the app router. Plain
+clicks navigate client-side; modifier and middle clicks retain native behavior.
+Do not intercept every click in a host `onNavigate`.
+
+`DatePickerInput.isNonModal` defaults to `false`; opting in lets an outside click
+both close the calendar and reach the clicked control. The command form's
+`CalendarField` forwards the same prop.
+
 ## Choose the semantic control first
 
 | Need | Control | Controlled contract |

package/package/corpus/skills/cratis-components-data-surfaces/SKILL.md

@@ -132,6 +132,11 @@ Camera/controls contract (`Canvas.tsx`, `CanvasHandle.ts`):
 
 Persist item edits in the host, not in camera callbacks. Browser-test gestures and dimensions. For jsdom tests provide a `ResizeObserver` substitute where required; Pixi integration still needs a real browser signal.
 
+For bound-table server filtering, query-state isolation, refreshed selection and
+localized numbered pagination, read
+[Query table updates](references/query-table-updates.md). Page-local filtering is
+still the default; `serverQuery` is opt-in.
+
 ## 4. Public Chat: bind the host's messages and outcomes
 
 The public `@cratis/components/Chat` exports **`ChatConversation`**, **`ChatSidebar`**, **`ChatSidebarForObservableQueries`**, **`ChatTopicList`** and their types. It does **not** export the Kit `Chat` component or expose a `Chat/Kit` package subpath (`Source/Chat/index.ts`, `Source/package.json`). **`Chat` is exported through `@cratis/components/Canvas`** via the Kit barrel (`Source/Canvas/index.ts`, `Source/Chat/Kit/index.ts`). Prefer the non-spatial Chat subpath for ordinary host-data conversations; importing Canvas brings its Pixi edge.

package/package/corpus/skills/cratis-components-data-surfaces/references/query-table-updates.md

@@ -0,0 +1,51 @@
+<!-- Copyright (c) Cratis. All rights reserved. -->
+<!-- Licensed under the MIT license. See LICENSE file in the project root for full license information. -->
+
+# Query tables: server state, selection and pagination
+
+Requires Components 4.35.1 for all table features described here, including serverQuery, filteredEmptyMessage, pageLinks and refreshed selection; check `yarn why @cratis/components`, or retain the older table API and host-owned filtering, pagination and selection reconciliation.
+
+## Server sorting and filtering are opt-in
+
+`DataTableForQuery`, `DataTableForObservableQuery` and `DataPage` accept
+`serverQuery`. Without it, sorting and filtering affect only the
+loaded page, not the complete result set.
+
+- Supply `toArguments` to translate search text and column filters to query
+  arguments. The backend must apply those arguments itself.
+- Sorting uses Arc `sortBy`/`sortDirection`; `sortFields` maps column names to
+  server fields when necessary.
+- Return `IQueryable` or use MongoDB `Observe` so sorting precedes paging.
+- State changes return to page one; search is debounced by 300 ms by default.
+  Rows are rendered as the server returns them, not filtered a second time.
+
+Do not present a page-local search as a complete-dataset search.
+`filteredEmptyMessage` replaces `emptyMessage` when a search/filter has no rows.
+Provider messages distinguish `filteredEmpty` (this page) from
+`filteredEmptyServer` (server result). `onGlobalFilterChange` reports search text
+as the user types; it does not implement backend search.
+
+## Query state and selection
+
+With Arc and Arc React 22.122 or later, changing bound query arguments shows
+loading instead of the previous arguments' rows, failure or access-denied state.
+Returning to cached arguments avoids a loading flash. A completed
+unsuccessful result is a failure, not an empty success; unauthorized stays access
+denied. The query-bound chat sidebar also distinguishes these outcomes.
+
+Bound tables and `DataPage` reconcile selection against refreshed
+rows by `dataKey`, clearing it when the selected row disappears. A controlled
+selection is reported through `onSelectionChange`, never forcibly overridden.
+Use stable keys and exercise argument changes and removed selections in specs.
+
+## Pagination and localization
+
+`pageLinks` is off by default. Set it to `true` or `{ siblings, boundaries }` on
+`TablePaginator`, a bound table or `DataPage` for numbered links with ellipses.
+The current button has `aria-current="page"`; the old page-count info is hidden.
+The `pages`, `page`, `ellipsis` parts support styling; `page(n)` and `pages`
+messages name the controls. Provider paginator messages or
+`ariaLabels.range(start, end, total)` localize the range text too.
+
+For a custom pager, `paginatorPages` and `PaginatorPageItem` export the same
+windowing logic. Do not hard-code English accessible names in a localized host.

package/package/corpus/skills/cratis-components-schema-editor/references/tree-layout.md

@@ -36,6 +36,7 @@ the controlled host applies and reports its own changes.
 | --- | --- |
 | `concepts: PropertyConcept[]` | Named types with a `PropertyType`; saved as `x-concept`. Overrides a surrounding `PropertyConceptsProvider` |
 | `allowRequired` | Toggle membership in the object's `required` names |
+| `allowGeneratedProperty` | Boolean or per-property predicate; offers the `x-generated` toggle |
 | `allowKeyProperty` | Boolean or `(property, context) => boolean`; `x-key`, one per object |
 | `isPropertyProtected` | Prevent rename/removal, not every possible edit |
 | `validatePropertyName` | `(name, property, siblings) => string \| undefined`, after built-in checks |
@@ -60,3 +61,20 @@ The subpath exports `PropertyType`, `PropertyConceptsProvider`,
 Use the typed property-tree helpers for a controlled host, rather than treating
 `required` as a property boolean. Schema keywords are `x-concept`, `x-key`, and
 the parent object's `required: string[]`.
+
+Requires Components 4.35.0 for generated-property preservation, schema keyword bags and unique identifiers; check `yarn why @cratis/components`, or retain the older tree contract.
+
+Controlled hosts handle `onSetGeneratedProperty` and carry
+`Property.isGenerated`, `vendorKeywords` and `itemVendorKeywords`; the exported
+`GENERATED_KEYWORD` names `x-generated`. Without an offered toggle, including
+read-only mode, generated properties show a marker styled through `generated`.
+Also carry `schemaKeywords` and `itemSchemaKeywords` for unmodeled
+standard JSON Schema keywords. Dropping these bags in a host loses constraints
+and annotations even though the editor preserves them. Untouched properties now
+round-trip their original shape and order; a type change drops only keywords
+inapplicable to the new type (including old array-item annotations).
+
+`PropertyType.UniqueIdentifier` writes a string with `format: uuid`
+and reads either `uuid` or `guid`. Localize it with `typeUniqueIdentifier`.
+`GlyphMenu` and `PropertyTypeGlyph` are exported for host-owned single-choice
+type lists.

package/package/corpus/skills/cratis-components-stepper-command-dialog/SKILL.md

@@ -10,6 +10,17 @@ license: MIT
 user moves with Previous and Next; Submit appears on the last step once every
 field across every step is valid.
 
+## Dialog dismissal and refusal
+
+Requires Components 4.36.0 for independent dismissal controls; check `yarn why @cratis/components`, or use the older `dismissable` contract.
+
+`Dialog` and `CommandDialog` accept independent `dismissOnOutsideClick`,
+`closeOnEscape` and `showCloseButton`; each falls back to `dismissable`. Busy
+dialogs cannot be dismissed. The busy confirm remains focusable as
+`aria-disabled` and ignores duplicate activation; a refused confirm restores
+focus and announces the provider's `refused` message. Do not replace it with a
+disabled button that loses focus or close the dialog on validation refusal.
+
 ## Verified product sources
 
 | Package | Verified from |

package/package/corpus/skills/cratis-fundamentals-type-discovery/SKILL.md

@@ -146,6 +146,19 @@ services.AddSingleton<IReportFormatters, ReportFormatters>();
 Search for every remaining reference before deleting, so nothing else was
 relying on a registration for a different reason.
 
+## Reuse derived-type discovery
+
+Requires Fundamentals and its generator 7.26.1 for per-universe caching plus nested-generic/experimental-type generator fixes; check `dotnet list package`, or keep the older construction path until upgrading.
+
+Use `Cratis.Serialization.DerivedTypes.For(types)` when several service
+collections share the same `ITypes` instance. It returns one shared `DerivedTypes`
+per universe, held weakly; distinct universes stay isolated. Do not construct one
+per scope or replace a host's explicit universe with `DerivedTypes.Instance`.
+
+The generator omits nested open-generic types from referenced Cratis packages
+and handles referenced `[Experimental]` diagnostic IDs. Upgrade the generator
+rather than editing its output to bypass those build failures.
+
 ## What breaks
 
 - **`[Singleton]` does not resolve.** The using directive is

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

@@ -11,32 +11,22 @@ license: MIT
 
 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 come from `Cratis/Orleans` source.
-
-| Packages | Sources |
-| --- | --- |
-| `Cratis.Orleans`, `Cratis.Orleans.Storage` | `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` | `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` | `Source/Orleans.Chronicle/StateMachines/EventSourcedStateMachine.cs`; [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`, `JobsOptions.cs`).
+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.
+
+- Job: derive `Job<TRequest, TJobState>`; the request is a class implementing `IJobRequest`, the state derives `JobState`. Implement `PrepareSteps(TRequest)` returning `Task<IImmutableList<JobStepDetails>>`.
+- 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>>`.
+- Implement `PrepareStep(TRequest)` → `Task<Result<PrepareJobStepError>>`; `InitializeState(TRequest)` → `ValueTask`, called after preparation succeeds; and `PerformStep(TState, CancellationToken)` → `Task<Catch<JobStepResult>>`. `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.
 
-- Job: derive `Job<TRequest, TJobState>`; the request is a class implementing `IJobRequest`, the state derives `JobState` (`Job.cs`). Implement `PrepareSteps(TRequest)` returning `Task<IImmutableList<JobStepDetails>>` (`Job.Steps.cs`).
-- 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`).
-- Implement `PrepareStep(TRequest)` → `Task<Result<PrepareJobStepError>>`; `InitializeState(TRequest)` → `ValueTask`, called after preparation succeeds; and `PerformStep(TState, CancellationToken)` → `Task<Catch<JobStepResult>>` (`JobStep.cs`). `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`, `Documentation/how-to/host-the-silo.md`, and `orleans.md`).
+`PerformStep` runs **outside the activation context** with a deep-copied state snapshot. Mutating that snapshot does not persist it; do not access/write grain `State` directly from background work. A specification host such as Orleans.TestKit must register `DeepCopier<TState>`.
 
-`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`). Keep progress/state coordination on grain calls. Requires Cratis.Orleans 1.16.2 for framework-owned stop reporting; there, do not report cancellation again from a `PerformWork` override (`Documentation/concepts/jobs.md`).
+Requires Cratis.Orleans 1.19.0 for `TryInvokeOnActivation` to coordinate state/checkpoints on the current activation, including during deactivation. Call it only from the run's background work. Keep callbacks local: capture copied inputs, call remote systems outside the callback, then commit in a second callback. Never call another grain, nest and await another callback, or start unawaited work inside it. Inspect `ActivationCallbackRejected` (`NoRun`, `StaleRun`, `Closed`, `Cancelled`); exceptions propagate. The optional `queueCancellationToken` cancels waiting callbacks only; started callbacks finish. Stop/deactivation waits for started callbacks and work to settle; `JobsOptions.StepStopTimeout` defaults to 10 seconds and `JobStepError.StopTimedOut` is not proof of quiescence. Requires 1.16.2 for framework-owned stop reporting: do not report cancellation again from a `PerformWork` override.
 
 ## 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`).
+Default steps all use `JobStepStage.First`. Prefer independent fan-out. Use stages only when correctness requires earlier work to finish.
 
 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<,,>`:
 
@@ -52,64 +42,62 @@ protected override Task<IImmutableList<JobStepDetails>> PrepareSteps(RecoveryReq
     ]);
 ```
 
-Import `System.Collections.Immutable` and `Cratis.Orleans.Jobs` in that job file. `CreateStep<TStep>` takes the **grain interface**, not the implementation (`Job.Steps.cs`). Its stage overload accepts `JobStepStage`, with implicit integer conversion (`Source/Orleans.Storage/Jobs/Stages/JobStepStage.cs`).
+Import `System.Collections.Immutable` and `Cratis.Orleans.Jobs` in that job file. `CreateStep<TStep>` takes the **grain interface**, not the implementation. Its stage overload accepts `JobStepStage`, with implicit integer conversion.
 
-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`).
+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`.
 
-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`, namespace `Cratis.Orleans.Jobs.Stages`). Do not silently continue when a later stage relies on the failed output.
+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` (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
+Requires 1.25.0 for durable step plans: preparation requests must round-trip through the host's JSON options. Invalid plans return `StartJobError.InvalidStepPlan`. Recovery reuses identities and requests, prepares only unsaved steps, and never calls `PrepareSteps` again. Put retry-safe initialization needed before start **and** resume in `OnBeforeDispatchingJobSteps(JobStepDispatchContext)`, after the respective start/resume hook. `InitializationMayBeIncomplete` flags recovery from preparing/starting, not exactly-once initialization. A failed hook dispatches nothing; recovery never replays the start hook. A legacy preparing/starting job without a saved plan returns `CannotResumeJobError.MissingStepPlan` rather than inventing identities.
 
-`IGrainFactory.GetJobsManager(scope, namespace)` resolves the manager (`JobsManagerExtensions.cs`). `IJobsManager.Start<TJob,TRequest>(request)` returns `Result<JobId, StartJobError>`; inspect its error before telling a caller that a job started (`IJobsManager.cs`). Start success is not completed work; observe the job's status/outcomes.
+## 3. Start locally and recover every scope
 
-`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`). `Rehydrate()` completes after loading/preparing interrupted jobs, **before** its bounded background drain has resumed them all.
+Requires 1.18.0 for the singleton local service `Cratis.Orleans.Jobs.IJobs`, registered by `AddCratisOrleans`. Prefer `Start<TJob,TRequest>(new JobKey(scope, namespace), request)` (or its explicit job-id overload), `Stop(key, jobId)` and `Delete(key, jobId)` during rolling upgrades. Generic `IJobsManager.Start`/`GetJobsOfType` send types through a manager that may run an older release and cannot decode them.
 
-`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`).
+Inspect `Result<JobId, StartJobError>` before telling a caller that work started. `FailedStartingSomeJobSteps` means remaining work is still running, not that nothing started; `AllJobStepsFailedStarting` means no step started. Start success is not completion. Match `StopJobResult`/`DeleteJobResult`: accepted, `NotFound`, `UnknownJobType`, or `Refused` with the job's error. Unknown types require a release that knows the type; exceptions propagate. Deletion acceptance is not completed removal. Third-party storage should override `IJobStorage.GetJobType` with a metadata-only read; its fallback reads the request too.
 
-## 4. Know what storage retains
+`IGrainFactory.GetJobsManager(scope, namespace)` remains available. `IJobsManager.Resume(JobId)` returns **`Task<bool>`**; false means nothing took the job: do not wait for a completion callback as though resumption succeeded. True may also mean already running or finalized. `IJobsManager.Stop` returns `Result<StopJobError>`; preserve a persistence refusal. `Rehydrate()` returns after loading/preparing interrupted jobs, before its bounded background drain resumes them all. `StartStepsInBackground = true` moves step preparation/start to the next turn after durability; later failures belong to the job, not Start.
 
-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`, `JobsOptions.cs`).
+Requires 1.17.0 for automatic recovery on silo activation/member death. Provide singleton `IJobsManagerKeys` implementations on **every silo**, enumerating all host-owned scope/namespace pairs through `GetKeys(CancellationToken)`. The default remembers only keys used in this process: it is not a durable catalog. Providers run outside request scope; never inject a current tenant/user or scoped database. Requires 1.23.3 (1.24.2 for provider construction failures) for automatic recovery retries of failed providers/managers, from 1 second doubling to 60 seconds until success or silo shutdown. There is no periodic sweep by default. `AddCratisOrleans` registers recovery; separately configured silos need `AddCratisOrleansJobsRecovery()` (`Cratis.Orleans.Hosting`).
 
-**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`). 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`); do not read deleted successful step state later.
+Read [lifecycle and placement](references/lifecycle-and-placement.md) for drain/admission, bounded attempts, placement, custom storage compatibility and step test runs.
 
-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`, `WriteState`; `Documentation/concepts/jobs.md`). 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.
+## 4. Know what storage retains
 
-## 5. Register storage and budget concurrency
+Successful jobs clear themselves by default; override `KeepAfterCompleted` to retain state. Jobs completed with failures default to `KeepAfterCompletedWithFailures = true`, but retention cleanup still applies.
+
+Keeping a job does not keep successful step state: successful **steps delete their state**. Failed step state is retained. A durable callback receipt, deduplication set or result must live on the **job** (and be persisted), not only on a successful step. Deliver external callbacks to a method on the job's grain interface and preserve `WriteState()`'s `Catch` failure: do not acknowledge a failed write. Step state is not a callback inbox, and a running snapshot does not see later writes automatically.
 
-`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`). They are storage boundaries, not authorization checks.
+## 5. Register storage and budget concurrency
 
-Choose one storage registration alongside `AddCratisOrleans`:
+`IJobsStorage.GetFor(scope, namespace)` returns `JobsStorage`. Scope and namespace are opaque host-owned storage coordinates, 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`; in-memory `InMemory/InMemoryJobsStorage.cs`.
-
-### SQL schema creation
+| `AddCratisOrleansMongoDBJobsStorage` | `.Storage.MongoDB` / `Cratis.Orleans.Setup` | Durable MongoDB; default database `{scope}+jobs[+{namespace}]`, overridable |
+| `AddCratisOrleansSqlJobsStorage` | `.Storage.Sql` / `Cratis.Orleans.Setup` | Durable EF Core; `OptionsResolver(scope, namespace)` selects `DbContextOptions<JobsDbContext>` |
+| `AddCratisOrleansInMemoryJobsStorage` | `.Storage` / `Cratis.Orleans.Storage` | Specs/development; restart loses state |
 
-The product's SQL setup docs say to create the schema yourself. **the provider applies migrations automatically**: `SqlJobsStorage.GetFor` calls `EnsureSchema`, which calls `dbContext.Database.Migrate()` before constructing storage (`Source/Orleans.Storage.Sql/SqlJobsStorage.cs`). 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`). This resolves the documentation conflict from source, not from a release-note inference.
+The SQL provider calls `dbContext.Database.Migrate()` automatically before constructing storage. Do not substitute `EnsureCreated` or hand-create tables; grant migration permissions and choose scope-to-database mapping deliberately. `IJobsStorage.Reset()` clears the cache; the next resolution migrates again. There is no MySQL/MariaDB jobs provider.
 
-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`).
+`JobsOptions` properties are **init-only**: supply a constructed instance through the host's options mechanism, not assignment in `Configure(options => …)`.
 
 | Option | Default | Purpose |
 | --- | --- | --- |
-| `MaxParallelSteps` | `max(1, ProcessorCount - 1)` when unset | Actual execution throttle |
-| `MaxConcurrentStepStarts` | `16` | Startup/resume calls per job, not the execution limit |
+| `MaxParallelSteps` | `max(1, ProcessorCount - 1)` when unset | Execution throttle per silo |
+| `MaxConcurrentStepStarts` | `16` | Startup/resume calls per job, not 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 |
+| `StepCheckpointBatchInterval` | `100` | Batches between durable checkpoints |
+| `StepCheckpointFlushInterval` | `5 seconds` | Timed flush; nonpositive disables it |
+| `DeadJobThreshold`, `CleanupCadence` | `1 hour` each | Preparation-with-no-steps scavenging; saved plans are excluded |
+| `TerminalJobRetention` | `7 days` | Terminal history; `Timeout.InfiniteTimeSpan` retains indefinitely |
 | `MaxTerminalJobsPerCleanup` | `100` | Bounded oldest-first cleanup page |
 
-Source: `JobsOptions.cs`. 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.
+Concurrency values below one become one. Retention does not delete preparing/running/stopped/removing jobs. Larger checkpoint intervals increase post-crash redelivery, not 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.
+Use [state-machines.md](references/state-machines.md) for `StateMachine<TStoredState>` and `EventSourcedStateMachine<TModel>`. 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.
+Verify planning, invalid/missing saved plans, idempotent redelivery, stop/resume/refusal, failed barriers/Unreachable, retention and persistence failures. Exercise durable storage restart recovery and SQL migration permissions. A build alone cannot establish crash recovery. Do not operate a live store merely to validate an example.