@cratis/pi 7.102.0 → 7.103.0

package/package/corpus/skills/orleans/references/streaming-api.md

@@ -0,0 +1,396 @@
+# Streaming, Broadcast Channels, and Observers API
+
+## Contents
+
+- Orleans Streams
+- Broadcast Channels
+- Observers
+- Stream Providers
+- Streams Programming API Details
+- Direct Calls vs Streams vs Broadcast vs Observers vs IAsyncEnumerable
+
+Detailed streaming and communication patterns from official Orleans documentation.
+
+## Orleans Streams
+
+Streams are virtual, always exist, never fail, identified by `StreamId` (namespace + key). Decouple data generation from processing in time and space.
+
+### Configuration
+
+```csharp
+// Silo — memory streams (dev only)
+siloBuilder.AddMemoryStreams("StreamProvider")
+    .AddMemoryGrainStorage("PubSubStore");
+
+// Silo — Azure Event Hubs
+siloBuilder.AddEventHubStreams("EventHubProvider", options =>
+{
+    options.ConfigureEventHub(eh => eh.Configure(o =>
+    {
+        o.ConnectionString = connectionString;
+        o.ConsumerGroup = "$Default";
+        o.Path = "my-hub";
+    }));
+    options.UseAzureTableCheckpointer(c => c.ConfigureTableServiceClient(storageConnection));
+});
+
+// Client
+clientBuilder.AddMemoryStreams("StreamProvider");
+```
+
+### Producing Events
+
+```csharp
+var streamProvider = this.GetStreamProvider("StreamProvider");
+var streamId = StreamId.Create("SensorData", this.GetPrimaryKeyString());
+var stream = streamProvider.GetStream<SensorReading>(streamId);
+await stream.OnNextAsync(new SensorReading { Value = 42.0 });
+```
+
+### Consuming Events — Implicit Subscription
+
+```csharp
+[ImplicitStreamSubscription("SensorData")]
+public class AggregatorGrain : Grain, IAggregatorGrain
+{
+    public override async Task OnActivateAsync(CancellationToken ct)
+    {
+        var streamProvider = this.GetStreamProvider("StreamProvider");
+        var stream = streamProvider.GetStream<SensorReading>(
+            StreamId.Create("SensorData", this.GetPrimaryKeyString()));
+
+        await stream.SubscribeAsync(
+            (reading, token) =>
+            {
+                // Process reading
+                return Task.CompletedTask;
+            });
+        await base.OnActivateAsync(ct);
+    }
+}
+```
+
+### Consuming Events — Explicit Subscription
+
+```csharp
+var stream = streamProvider.GetStream<Order>(StreamId.Create("Orders", "incoming"));
+
+StreamSubscriptionHandle<Order> handle = await stream.SubscribeAsync(
+    onNextAsync: (item, token) => ProcessAsync(item),
+    onErrorAsync: ex => HandleError(ex),
+    onCompletedAsync: () => Task.CompletedTask,
+    token: lastKnownToken); // resume from position
+
+// Unsubscribe
+await handle.UnsubscribeAsync();
+```
+
+### Delivery Semantics
+
+| Provider | Delivery | Ordering |
+|---|---|---|
+| Memory | Best-effort | FIFO per stream |
+| Azure Queue | At-least-once | FIFO per queue |
+| Event Hubs | At-least-once | Per partition |
+| Broadcast Channel | At-most-once | No guarantee |
+
+Rewindable streams support subscribing from arbitrary point using `StreamSequenceToken`.
+
+### IAsyncEnumerable (Orleans 7+)
+
+Request-response scoped streaming, not pub-sub:
+
+```csharp
+// Interface
+public interface IDataGrain : IGrainWithStringKey
+{
+    IAsyncEnumerable<DataItem> GetItems(
+        int count,
+        [EnumeratorCancellation] CancellationToken ct = default);
+}
+
+// Implementation
+public class DataGrain : Grain, IDataGrain
+{
+    public async IAsyncEnumerable<DataItem> GetItems(
+        int count,
+        [EnumeratorCancellation] CancellationToken ct = default)
+    {
+        for (int i = 0; i < count && !ct.IsCancellationRequested; i++)
+        {
+            yield return await FetchItem(i);
+        }
+    }
+}
+
+// Consumer
+await foreach (var item in grain.GetItems(100).WithCancellation(cts.Token))
+{
+    Process(item);
+}
+```
+
+Default batch size: 100. Configure with `.WithBatchSize(50)`.
+
+## Broadcast Channels
+
+Fire-and-forget broadcast to all implicitly subscribed grains. No persistence, no delivery guarantees.
+
+### Configuration
+
+```csharp
+siloBuilder.AddBroadcastChannel("announcements");
+```
+
+### Consumer
+
+```csharp
+[ImplicitChannelSubscription]
+public class NotificationGrain : Grain, INotificationGrain, IOnBroadcastChannelSubscribed
+{
+    public Task OnSubscribed(IBroadcastChannelSubscription subscription)
+    {
+        subscription.Attach<Announcement>(
+            item => OnAnnouncement(item),
+            ex => OnError(ex));
+        return Task.CompletedTask;
+    }
+
+    private Task OnAnnouncement(Announcement item)
+    {
+        // Process broadcast message
+        return Task.CompletedTask;
+    }
+}
+```
+
+### Producer
+
+```csharp
+var provider = client.GetBroadcastChannelProvider("announcements");
+var channelId = ChannelId.Create("system", Guid.Empty);
+var writer = provider.GetChannelWriter<Announcement>(channelId);
+await writer.Publish(new Announcement { Message = "System update" });
+```
+
+## Observers
+
+One-way async push notifications from grains to clients or other grains.
+
+### Observer Interface
+
+```csharp
+public interface IChatObserver : IGrainObserver
+{
+    [OneWay] // fire-and-forget
+    Task OnMessage(string user, string message);
+
+    Task OnUserJoined(string user);
+}
+```
+
+### Server-Side (ObserverManager)
+
+```csharp
+public class ChatRoomGrain : Grain, IChatRoomGrain
+{
+    private readonly ObserverManager<IChatObserver> _observers;
+
+    public ChatRoomGrain(ILogger<ChatRoomGrain> logger)
+    {
+        _observers = new ObserverManager<IChatObserver>(
+            TimeSpan.FromMinutes(5), logger);
+    }
+
+    public Task Subscribe(IChatObserver observer)
+    {
+        _observers.Subscribe(observer, observer);
+        return Task.CompletedTask;
+    }
+
+    public Task Unsubscribe(IChatObserver observer)
+    {
+        _observers.Unsubscribe(observer);
+        return Task.CompletedTask;
+    }
+
+    public Task SendMessage(string user, string message)
+    {
+        _observers.Notify(o => o.OnMessage(user, message));
+        return Task.CompletedTask;
+    }
+}
+```
+
+### Client-Side
+
+```csharp
+// Create observer
+var observerInstance = new ChatObserver();
+var observerRef = grainFactory.CreateObjectReference<IChatObserver>(observerInstance);
+
+// Subscribe
+var chatRoom = client.GetGrain<IChatRoomGrain>("lobby");
+await chatRoom.Subscribe(observerRef);
+
+// Cleanup — must call to avoid memory leaks (held as WeakReference)
+grainFactory.DeleteObjectReference<IChatObserver>(observerRef);
+```
+
+### Grain-as-Observer
+
+```csharp
+public class MonitorGrain : Grain, IMonitorGrain, IChatObserver
+{
+    public async Task StartMonitoring(string room)
+    {
+        var chatRoom = GrainFactory.GetGrain<IChatRoomGrain>(room);
+        await chatRoom.Subscribe(this.AsReference<IChatObserver>());
+    }
+
+    public Task OnMessage(string user, string message)
+    {
+        // Handle notification
+        return Task.CompletedTask;
+    }
+}
+```
+
+### Observer Execution Model
+
+- Non-reentrant, single-threaded per observer reference
+- `[Reentrant]` / `[AlwaysInterleave]` attributes don't affect observers
+- `CancellationToken` support added in Orleans 9.0
+
+## Stream Providers
+
+### Azure Event Hubs
+
+NuGet: `Microsoft.Orleans.Streaming.EventHubs`. Real-time ingestion, rewindable, supports replay from arbitrary point.
+
+```csharp
+siloBuilder.AddEventHubStreams("EventHubProvider", options =>
+{
+    options.ConfigureEventHub(eh => eh.Configure(o =>
+    {
+        o.ConnectionString = connectionString;
+        o.ConsumerGroup = "$Default";
+        o.Path = "my-hub";
+    }));
+    options.UseAzureTableCheckpointer(c =>
+        c.ConfigureTableServiceClient(storageConnection));
+});
+```
+
+### Azure Queue (AQ)
+
+NuGet: `Microsoft.Orleans.Streaming.AzureStorage`. Uses pulling agents inside silos. Not rewindable. Does not guarantee FIFO on failures.
+
+```csharp
+siloBuilder.AddAzureQueueStreams("AQProvider", optionsBuilder =>
+    optionsBuilder.ConfigureAzureQueue(options =>
+        options.Configure(opt =>
+            opt.QueueServiceClient = new QueueServiceClient(endpoint, credential))));
+```
+
+### Aspire Streaming Integration
+
+```csharp
+// Azure Queue with Aspire
+var storage = builder.AddAzureStorage("storage");
+var queues = storage.AddQueues("streaming");
+var orleans = builder.AddOrleans("cluster")
+    .WithStreaming("AQProvider", queues);
+
+// In-memory streaming
+orleans.WithMemoryStreaming("MemoryProvider");
+
+// Broadcast channels
+orleans.WithBroadcastChannel("BroadcastChannel");
+```
+
+### Pub-Sub Management
+
+Managed by `PubSubRendezvousGrain`, persisted via `"PubSubStore"`:
+
+```csharp
+siloBuilder.AddAzureTableGrainStorage("PubSubStore",
+    options => options.TableServiceClient = new TableServiceClient(endpoint, credential));
+```
+
+## Streams Programming API Details
+
+### Core Interfaces
+
+```csharp
+public interface IAsyncObserver<in T>
+{
+    Task OnNextAsync(T item, StreamSequenceToken token = null);
+    Task OnCompletedAsync();
+    Task OnErrorAsync(Exception ex);
+}
+
+public interface IAsyncObservable<T>
+{
+    Task<StreamSubscriptionHandle<T>> SubscribeAsync(IAsyncObserver<T> observer);
+}
+```
+
+### Failure Recovery
+
+Consumer must re-attach processing logic in `OnActivateAsync`:
+
+```csharp
+public override async Task OnActivateAsync(CancellationToken ct)
+{
+    var stream = this.GetStreamProvider("SP").GetStream<string>(streamId);
+    var handles = await stream.GetAllSubscriptionHandles();
+    foreach (var handle in handles)
+        await handle.ResumeAsync(this);
+}
+```
+
+### Implicit Subscriptions with IStreamSubscriptionObserver
+
+```csharp
+[ImplicitStreamSubscription("MyNamespace")]
+public class MyGrain : Grain, IMyGrain, IStreamSubscriptionObserver
+{
+    public async Task OnSubscribed(IStreamSubscriptionHandleFactory handleFactory)
+    {
+        var handle = handleFactory.Create<string>();
+        await handle.ResumeAsync(this);
+    }
+}
+```
+
+### Key Characteristics
+
+- Subscriptions are per-grain (not per-activation) — durable across activations
+- Multiple producers and consumers per stream
+- Subscribing X times delivers event X times
+- Rewindable streams (Event Hubs) support replay from `StreamSequenceToken`
+
+### Why Orleans Streams?
+
+Existing stream systems (Kafka, Storm, Spark) are for uniform dataflow graphs. Orleans Streams target:
+1. **Flexible processing logic** — imperative, functional, Rx, stateful, with side effects
+2. **Dynamic topologies** — add/remove nodes at runtime
+3. **Fine-grained granularity** — each stream link is an independent entity
+4. **Distribution** — scalable, elastic, reliable
+
+Typical use: per-user streams with different processing logic per user, subscriptions changing dynamically.
+
+## Direct Calls vs Streams vs Broadcast vs Observers vs IAsyncEnumerable
+
+| Feature | Direct call | Streams | Broadcast | Observers | IAsyncEnumerable |
+|---|---|---|---|---|---|
+| Purpose | Command/query a known owner | Decoupled event flow | Loss-tolerant fan-out | Live callback to a connected subscriber | Progressive response to one caller |
+| Persistence | No message persistence | Provider-dependent | No | No | No |
+| Delivery | At-most-once by default; retries can duplicate | Provider-dependent | Best-effort | Best-effort for clients | Bound to the request |
+| Subscription | None | Implicit or explicit | Implicit | Manual and renewable | None |
+| Replay/history | No | Provider-dependent | No | No | No |
+| Lifetime | One request/response | Long-lived logical subscription | Active implicit subscriber mapping | Client/object reference lifetime | One enumeration/call |
+| Primary use | Typed result, completion, error | Dynamic pub/sub and queue-backed processing | Cache invalidation, latest-value hints, announcements | UI/client notifications | Large/progressive result sets with backpressure |
+
+Use a one-way request only as an advanced direct-call variant when the caller explicitly accepts no completion, error, result, or receipt guarantee. Do not treat one-way calls, broadcast channels, or observers as durable messaging.

package/package/corpus/skills/orleans/references/testing-patterns.md

@@ -0,0 +1,210 @@
+# Orleans Testing Patterns
+
+## Contents
+
+- Choose The Harness First
+- Runtime-Only Orleans Tests
+- Shared AppHost Fixture For Real Topology Tests
+- Mix AppHost Infra With `WebApplicationFactory`
+- TUnit Per-Session Sharing
+- SignalR And Browser Flows
+- Failure Diagnostics
+- Anti-Patterns
+
+Use this reference when the task is about testing Orleans grains together with real hosting, HTTP/SignalR surfaces, Aspire resources, or browser flows.
+
+These patterns are grounded in working test harnesses used in `AIBase` and `WA.Storied.Agents`: one shared AppHost fixture for the distributed topology, an optional `WebApplicationFactory` layer for direct Host DI/grain access, and separate browser contexts per UI test.
+
+Sharing the AppHost reduces startup cost and does not make the suite sequential. Keep tests parallel, make fixture helpers concurrency-safe, and use unique grain IDs, tenant IDs, storage prefixes, database keys, connections, and browser contexts per test. Constrain only the smallest keyed group that performs destructive changes to the exact same shared state.
+
+## Choose The Harness First
+
+| Need | Best Harness | Why |
+|---|---|---|
+| Grain runtime behavior only | `InProcessTestCluster` | Fastest Orleans-focused harness without HTTP/UI layers |
+| Real API, SignalR, SSE, or AppHost wiring | Shared Aspire/AppHost fixture | Exercises the actual distributed topology and resource graph |
+| Direct Host DI services or `IGrainFactory` from the hosted app | Shared Aspire/AppHost fixture + `WebApplicationFactory<TEntryPoint>` | Keeps real infra while letting tests resolve services from the Host container |
+| Browser automation against a co-hosted Orleans app | Shared Aspire/AppHost fixture + Playwright | Reuses one browser process and one AppHost boot, but isolates browser state per test |
+
+## Runtime-Only Orleans Tests
+
+When the test is purely about grain scheduling, persistence, reentrancy, or state transitions, stay close to Orleans and use `InProcessTestCluster`:
+
+```csharp
+var builder = new InProcessTestClusterBuilder();
+builder.ConfigureSilo(siloBuilder =>
+{
+    siloBuilder.AddMemoryGrainStorageAsDefault();
+});
+
+await using var cluster = await builder.BuildAndStartAsync();
+var grain = cluster.GrainFactory.GetGrain<IOrderGrain>(Guid.NewGuid());
+
+await grain.SubmitAsync(new SubmitOrder("PO-42"));
+var state = await grain.GetStateAsync();
+```
+
+Use this harness when HTTP, SignalR, and AppHost resources are irrelevant to the assertion.
+
+## Shared AppHost Fixture For Real Topology Tests
+
+Use Aspire when the assertion depends on the actual Orleans host plus the real surrounding resources:
+
+```csharp
+public sealed class AspireTestFixture : IAsyncDisposable
+{
+    private DistributedApplication? _app;
+
+    public DistributedApplication App =>
+        _app ?? throw new InvalidOperationException("App not initialized.");
+
+    public string HostUrl { get; private set; } = string.Empty;
+
+    public async Task InitializeAsync()
+    {
+        var builder = await DistributedApplicationTestingBuilder.CreateAsync<Projects.My_AppHost>();
+
+        builder.Services.AddLogging(logging =>
+        {
+            logging.ClearProviders();
+            logging.AddConsole();
+            logging.SetMinimumLevel(LogLevel.Warning);
+            logging.AddFilter("Aspire.Hosting.Dcp", LogLevel.Warning);
+            logging.AddFilter("Aspire.Hosting.Backchannel", LogLevel.Critical);
+        });
+
+        _app = await builder.BuildAsync();
+        await _app.StartAsync();
+
+        using var cts = new CancellationTokenSource(TimeSpan.FromMinutes(1));
+        await _app.ResourceNotifications.WaitForResourceHealthyAsync("host", cts.Token);
+
+        HostUrl = _app.CreateHttpClient("host", "http").BaseAddress?.ToString()
+            ?? throw new InvalidOperationException("Host URL was not resolved.");
+    }
+
+    public HttpClient CreateApiClient() => App.CreateHttpClient("host", "http");
+}
+```
+
+This is the right shape for:
+
+- HTTP endpoint tests
+- SignalR/SSE/OpenResponses tests
+- admin or operator UI tests
+- Orleans flows that require the real host pipeline, auth, or middleware
+
+## Mix AppHost Infra With `WebApplicationFactory`
+
+This is the production-style pattern for co-hosted Orleans apps: boot infrastructure in Aspire once, then create a `WebApplicationFactory` over the Host/API assembly for direct DI and grain access.
+
+```csharp
+public sealed class TestApplication
+    : WebApplicationFactory<HostEntryPointMarker>, IAsyncDisposable
+{
+    private static readonly AspireTestFixture SharedFixture = new();
+    private readonly Dictionary<string, string?> _overrides = new(StringComparer.OrdinalIgnoreCase);
+
+    protected override void ConfigureWebHost(IWebHostBuilder builder)
+    {
+        builder.UseEnvironment(Environments.Development);
+        builder.ConfigureAppConfiguration((_, config) => config.AddInMemoryCollection(_overrides));
+    }
+
+    public async Task InitializeAsync()
+    {
+        await SharedFixture.InitializeAsync();
+
+        var tables = await SharedFixture.App.GetConnectionStringAsync("tables");
+        var blobs = await SharedFixture.App.GetConnectionStringAsync("blobs");
+
+        _overrides["ConnectionStrings:Tables"] = tables;
+        _overrides["ConnectionStrings:Blobs"] = blobs;
+
+        CreateClient();
+    }
+
+    public AsyncServiceScope CreateScope() => Services.CreateAsyncScope();
+
+    public HttpClient CreateApiClient()
+    {
+        var client = CreateClient(new WebApplicationFactoryClientOptions { AllowAutoRedirect = false });
+        client.Timeout = TimeSpan.FromMinutes(5);
+        return client;
+    }
+}
+```
+
+Use this when the test needs:
+
+- `IGrainFactory`
+- repositories or managers from DI
+- direct access to runtime services
+- real HTTP clients and hub connections against the same host
+- whichever async fixture contract the test framework expects: xUnit, TUnit, or a repo-local wrapper
+
+## TUnit Per-Session Sharing
+
+For TUnit-based Orleans suites, keep the AppHost boot outside individual tests:
+
+```csharp
+[ClassDataSource<TestApplication>(Shared = SharedType.PerTestSession)]
+public sealed class OrderGrainIntegrationTests(TestApplication app)
+{
+    [Test]
+    public async Task Order_grain_persists_state_through_real_host()
+    {
+        await using var scope = app.CreateScope();
+        var grainFactory = scope.ServiceProvider.GetRequiredService<IGrainFactory>();
+
+        var grain = grainFactory.GetGrain<IOrderGrain>(Guid.NewGuid());
+        await grain.SubmitAsync(new SubmitOrder("PO-42"));
+
+        var state = await grain.GetStateAsync();
+        await Assert.That(state.Number).IsEqualTo("PO-42");
+    }
+}
+```
+
+The same pattern works for API-only tests with `ClassDataSource<AspireTestFixture>(Shared = SharedType.PerTestSession)`.
+
+Do not add `[NotInParallel]` to the class or force one test module/worker merely because the fixture is shared. If a maintenance test drops a shared schema or resets the whole cluster, give only those destructive tests the same keyed non-parallel constraint.
+
+## SignalR And Browser Flows
+
+For SignalR or UI flows, keep connection and browser helpers on the shared fixture:
+
+```csharp
+public HubConnection CreateAgentHubConnection(string token)
+{
+    var hubUrl = new Uri(new Uri(HostUrl), "/agenthub");
+
+    return new HubConnectionBuilder()
+        .WithUrl(hubUrl, options =>
+        {
+            options.AccessTokenProvider = () => Task.FromResult(token)!;
+            options.Headers["Authorization"] = $"Bearer {token}";
+            options.Transports = HttpTransportType.LongPolling;
+        })
+        .WithAutomaticReconnect()
+        .Build();
+}
+```
+
+For Playwright:
+
+- initialize Playwright once in the shared fixture
+- create a new browser context per test
+- set `BaseURL`, viewport, and `IgnoreHTTPSErrors` in the helper, not inline in every test
+
+## Failure Diagnostics
+
+Follow the `SKILL.md` Diagnostic Output Budget: keep progress/ANSI visible, collect Warning/Error/Critical logs in a size-bounded collector, and show only the exact test/resource failure, root exception, and relevant stack frames (at most 80 lines / 8 KiB per response). Never print the full collector on HTTP 500, startup failures, or crashes. Link Playwright screenshots/HTML and inspect only bounded resource-error excerpts when health waits fail. Preserve the original exception and runner exit code.
+
+## Anti-Patterns
+
+- Creating `DistributedApplicationTestingBuilder.CreateAsync<...>()` inside each test method
+- Booting a second Orleans client inside a co-hosted Host test when the app already uses `UseOrleans`
+- Copy-pasting local connection strings into tests instead of resolving them from `SharedFixture.App`
+- Using in-memory substitutes for persistence-sensitive or streaming-sensitive integration tests
+- Sharing a Playwright page or browser context across tests instead of sharing only the browser process

package/package/corpus/skills/platform-detection/LICENSE

@@ -0,0 +1,23 @@
+The MIT License (MIT)
+
+Copyright (c) .NET Foundation and Contributors
+
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package/corpus/skills/platform-detection/NOTICE

@@ -0,0 +1,17 @@
+Test Platform and Framework Detection
+Copyright (c) .NET Foundation and Contributors
+Licensed under the MIT License. See LICENSE.
+
+Upstream source: https://github.com/dotnet/skills/blob/a6bf43ab61967c30919334986515163ab24d7635/plugins/dotnet-test/skills/platform-detection/SKILL.md
+
+Changes made by Cratis:
+
+LICENSE:
+- Copy upstream MIT license and copyright verbatim.
+
+SKILL.md:
+- Normalize frontmatter serialization, add MIT license where absent; preserve name and description.
+- Add marked modification/source comment and applicability/Cratis precedence line with the skill-specific safety, ownership or compatibility caveat.
+- Rewrite the description to the Cratis shape (what it does, Use when, Not for) and drop references to skills that are not part of this corpus.
+
+NOTICE: Add this attribution, change list, and any download/execution disclosure.