@polymorphism-tech/morph-spec 7.5.0 → 7.7.0

package/framework/standards/STANDARDS.json

@@ -1495,9 +1495,9 @@
       "digest": "Vitest for unit tests, React Testing Library for component tests. Mock next/navigation with vi.mock. Test Server Actions with direct function calls. Use MSW for API mocking in component tests. Playwright for E2E tests against running app. Never test implementation details — test user behavior and output."
     },
     {
-      "id": "infrastructure-docker-easypanel-deploy",
-      "name": "easypanel deploy",
-      "path": "infrastructure/docker/easypanel-deploy.md",
+      "id": "infrastructure-docker-coolify-deploy",
+      "name": "coolify deploy",
+      "path": "infrastructure/docker/coolify-deploy.md",
       "category": "infrastructure",
       "subcategory": "docker",
       "tags": [
@@ -1508,17 +1508,20 @@
         "docker"
       ],
       "aliases": [
-        "easypanel",
+        "coolify",
         "docker deploy",
         "self-hosted",
         "VPS deployment",
-        "docker compose"
+        "docker compose",
+        "coolify api",
+        "ssh deploy"
       ],
       "anchors": {
-        "setup": "#easypanel-service-config",
-        "deployment": "#zero-downtime-deploys"
+        "setup": "#coolify-service-config",
+        "deployment": "#zero-downtime-deploys",
+        "ssh": "#triggering-a-deploy-via-ssh--api"
       },
-      "digest": "Create app in EasyPanel from container registry image. Configure environment variables in EasyPanel UI — not in Dockerfile. Use EasyPanel's managed Postgres/Redis for databases. Configure /health endpoint for health checks. Enable HTTPS via Let's Encrypt automatically. Use EasyPanel volumes for persistent storage."
+      "digest": "Coolify is the self-hosted Docker PaaS. No MCP/CLI exists — all access is via SSH into the VPS, hitting the Coolify API at localhost:8000/api/v1 with a server-side token (never printed, never leaves the SSH session). Configure environment variables in Coolify UI/API — not in Dockerfile. Configure /health endpoint for health checks. HTTPS via Let's Encrypt automatic (Traefik). Redeploys trigger via GET /deploy?uuid={uuid} over SSH."
     },
     {
       "id": "infrastructure-neon-setup",
@@ -1657,6 +1660,75 @@
         "edit-workflows": "#iterative-editing-workflows"
       },
       "digest": "Guidelines for generating project images with Gemini Image MCP — prompt patterns, aspect ratios, design-system-aware prompts, iterative editing, and assets.md format."
+    },
+    {
+      "id": "ai-agents-durable-workflows-hitl",
+      "name": "durable workflows hitl",
+      "path": "ai-agents/durable-workflows-hitl.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "workflow",
+        "durability"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "durable workflow",
+        "checkpoint",
+        "checkpointing",
+        "human in the loop",
+        "hitl",
+        "requestport",
+        "requestinfoevent",
+        "resume workflow",
+        "long running workflow",
+        "approval workflow",
+        "icheckpointstore"
+      ],
+      "anchors": {
+        "when": "#quando-usar-este-standard",
+        "hitl": "#human-in-the-loop-via-requestport",
+        "checkpointing": "#checkpointing--durável-sem-depender-de-azure",
+        "durable-task": "#azure-durable-task-extension--escape-hatch-not-default"
+      },
+      "digest": "HITL via RequestPort — a workflow node that pauses and waits for an external (human) response via RequestInfoEvent. Checkpointing is GA and Azure-free: CheckpointManager.CreateInMemory() for tests, CreateJson(FileSystemJsonCheckpointStore) for local-disk durability, or a custom ICheckpointStore (recommended against the project's own Postgres). Microsoft.Agents.AI.DurableTask (Azure Durable Task Scheduler) is documented as an escape hatch only, not adopted as default."
+    },
+    {
+      "id": "ai-agents-vector-data-extensions",
+      "name": "vector data extensions",
+      "path": "ai-agents/vector-data-extensions.md",
+      "category": "ai-agents",
+      "subcategory": null,
+      "tags": [
+        "ai-agents",
+        "maf",
+        "rag",
+        "vector-data"
+      ],
+      "stacks": [
+        "dotnet"
+      ],
+      "aliases": [
+        "microsoft extensions vectordata",
+        "vectorstorecollection",
+        "vector store abstraction",
+        "data ingestion",
+        "ingestion pipeline",
+        "semantic kernel connectors exception",
+        "pgvector connector",
+        "vectorstorewriter"
+      ],
+      "anchors": {
+        "naming-trap": "#a-pegadinha-de-nomenclatura-crítico--leia-antes-de-tudo",
+        "maturity": "#maturidade-atual-verificado-2026-07-06",
+        "decision-matrix": "#decision-matrix--custom-pgvector-vs-vectordata",
+        "data-ingestion": "#microsoftextensionsdataingestion-preview--pipeline-pattern-para-adoção-futura"
+      },
+      "digest": "Microsoft.Extensions.VectorData.Abstractions (GA) is the provider-agnostic vector-store abstraction; Microsoft.Extensions.DataIngestion (preview) is the companion ETL pipeline. Concrete connectors (Postgres, Qdrant, SQL Server...) ship under Microsoft.SemanticKernel.Connectors.* package names despite having nothing to do with Semantic Kernel — an explicit exception to ai-agents-setup's SK ban. Default RAG storage stays ai-agents-rag-custom-pgvector; adopt VectorData only for genuine multi-backend portability, since the Postgres connector is still prerelease."
     }
   ],
   "sharedAliases": {

package/framework/standards/ai-agents/durable-workflows-hitl.md

@@ -0,0 +1,191 @@
+# MAF Workflows — Checkpointing & Human-in-the-Loop
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** durable workflow, checkpoint, checkpointing, human in the loop, hitl, requestport, requestinfoevent, resume workflow, long running workflow, approval workflow, icheckpointstore, filesystemjsoncheckpointstore
+> **Read by Claude in:** plan (when `ai-agents-workflows` identifies a genuine HITL or long-running need) + implement (wiring `RequestPort` / `CheckpointManager`)
+
+**Verified against:** Microsoft.Agents.AI 1.0 GA (`Microsoft.Agents.AI.Workflows` namespace) + Microsoft.Agents.AI.DurableTask (prerelease, Azure-coupled — documented as an escape hatch, not adopted as default). Last-verified: 2026-07-06.
+
+---
+
+## Quando usar este standard
+
+Read `ai-agents-sweet-spot` and `ai-agents-workflows` first. This standard applies only once `ai-agents-workflows` has justified a Workflow **and** the reason is one of:
+
+- Long-running execution with a human-in-the-loop (HITL) approval step.
+- A workflow whose state must survive a process restart (deploy, crash, restart) between steps.
+
+If neither applies, a plain workflow (or no workflow at all — see `ai-agents-sweet-spot`) is enough; do not add checkpointing or `RequestPort` "just in case."
+
+---
+
+## Human-in-the-Loop via `RequestPort`
+
+HITL is modeled with `RequestPort` — a special node in the workflow graph that pauses execution and waits for an external (human) response instead of processing automatically.
+
+```csharp
+using Microsoft.Agents.AI.Workflows;
+
+// Request type the port sends out, response type it expects back.
+RequestPort<ApprovalRequest, bool> approvalPort =
+    RequestPort.Create<ApprovalRequest, bool>("RefundApproval");
+
+var workflow = new WorkflowBuilder(refundAnalyzerAgent)
+    .AddEdge(refundAnalyzerAgent, approvalPort)
+    .AddEdge(approvalPort, refundProcessorExecutor)
+    .WithOutputFrom(refundProcessorExecutor)
+    .Build();
+```
+
+Running the workflow, the caller watches for `RequestInfoEvent` and sends the human's answer back — the framework routes the response to the executor that made the request:
+
+```csharp
+await using StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, input);
+await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+{
+    switch (evt)
+    {
+        case RequestInfoEvent requestEvt:
+            // Surface requestEvt.Request to a human (dashboard, email, Slack, ...).
+            // This is where execution pauses until an external answer arrives.
+            bool approved = await GetHumanDecisionAsync(requestEvt.Request);
+            await run.SendResponseAsync(requestEvt.Request.CreateResponse(approved));
+            break;
+
+        case WorkflowOutputEvent outputEvt:
+            Console.WriteLine($"Workflow completed: {outputEvt.Data}");
+            break;
+    }
+}
+```
+
+**Agent tool-approval uses the same mechanism.** When an agent orchestration (sequential, concurrent, group chat) calls a tool marked as requiring approval, the workflow pauses and emits a `RequestInfoEvent` whose payload is a `ToolApprovalRequestContent` instead of a custom request type — no separate API to learn. See `ai-agents-multi-agent-patterns` for agent orchestration patterns this composes with.
+
+---
+
+## Checkpointing — durável sem depender de Azure
+
+Checkpointing is part of the **base, GA** `Microsoft.Agents.AI.Workflows` namespace — no extra/preview package required. A checkpoint captures the full workflow state at each superstep boundary: executor state, pending messages, and pending `RequestPort` requests (so a pending approval survives a restore).
+
+### Three storage options
+
+| Store | Durability | When to use |
+|-------|-----------|-------------|
+| `CheckpointManager.CreateInMemory()` | In-process only, lost on restart | Tests, demos, short-lived workflows |
+| `CheckpointManager.CreateJson(new FileSystemJsonCheckpointStore(dir))` | Local disk, survives process restart | Single-instance VPS deployments — no Azure, no preview package |
+| Custom `ICheckpointStore` implementation | Whatever backend you implement it against | **Recommended for production** — implement against the project's own Neon Postgres table, matching the ownership model already used by `ai-agents-rag-custom-pgvector` |
+
+```csharp
+using Microsoft.Agents.AI.Workflows;
+
+// Local-disk durability — no Azure dependency:
+var checkpointFolder = Directory.CreateDirectory("./checkpoints");
+CheckpointManager checkpointManager = CheckpointManager.CreateJson(
+    new FileSystemJsonCheckpointStore(checkpointFolder));
+
+StreamingRun run = await InProcessExecution.RunStreamingAsync(workflow, input, checkpointManager);
+await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+{
+    if (evt is SuperStepCompletedEvent stepEvt)
+    {
+        CheckpointInfo? checkpoint = stepEvt.CompletionInfo?.Checkpoint;
+        // Persist checkpoint.CheckpointId alongside the business record
+        // (e.g. the refund request row) so it can be resumed after a restart.
+    }
+}
+```
+
+Resuming after a restart — rehydrate into a **new** run instance from the last known checkpoint:
+
+```csharp
+StreamingRun resumedRun = await InProcessExecution.ResumeStreamingAsync(
+    newWorkflowInstance, savedCheckpoint, checkpointManager);
+
+await foreach (WorkflowEvent evt in resumedRun.WatchStreamAsync())
+{
+    // A pending RequestPort request is re-emitted here as a RequestInfoEvent —
+    // the paused approval survives the restart.
+    if (evt is RequestInfoEvent requestEvt) { /* re-surface to the human */ }
+}
+```
+
+### Custom executor state
+
+An executor with instance state beyond the message flow must opt in explicitly:
+
+```csharp
+internal sealed class RefundAnalyzerExecutor() : Executor("RefundAnalyzer")
+{
+    private const string StateKey = "AnalysisHistory";
+    private List<string> _history = [];
+
+    protected override ValueTask OnCheckpointingAsync(IWorkflowContext context, CancellationToken ct = default)
+        => context.QueueStateUpdateAsync(StateKey, _history);
+
+    protected override async ValueTask OnCheckpointRestoredAsync(IWorkflowContext context, CancellationToken ct = default)
+        => _history = await context.ReadStateAsync<List<string>>(StateKey);
+}
+```
+
+### `ICheckpointStore` — Neon/Postgres-backed (recommended production pattern)
+
+Implementing `ICheckpointStore` against the project's own Postgres database keeps checkpoint durability inside the same infrastructure the rest of the project already trusts (see `infrastructure-neon-setup`), instead of introducing a new storage dependency:
+
+```csharp
+public sealed class PostgresCheckpointStore(NpgsqlDataSource dataSource) : ICheckpointStore
+{
+    // Persist/retrieve checkpoint blobs in a workflow_checkpoints table
+    // (workflow_id, checkpoint_id, payload jsonb/bytea, created_at).
+    // Implement per the ICheckpointStore contract — see Microsoft.Agents.AI.Workflows docs.
+}
+```
+
+> **Security:** checkpoint storage is a trust boundary. Never restore a checkpoint from an untrusted or unauthenticated source — a tampered checkpoint can inject arbitrary workflow state.
+
+---
+
+## Azure Durable Task extension — escape hatch, not default
+
+`Microsoft.Agents.AI.DurableTask` (prerelease) adds durability backed by the **Azure Durable Task Scheduler**, including cost-efficient multi-day HITL waits with zero compute cost while paused. Even its "bring-your-own-compute / self-hosted" mode still requires a Durable Task Scheduler backend (`Microsoft.DurableTask.*.AzureManaged` packages) — self-hosted means your own worker process, not an Azure-free backend.
+
+This framework deploys to VPS/Coolify by default and does not adopt Azure as a default dependency (see `ai-agents-setup` §3.4 on Azure OpenAI). For that reason, `Microsoft.Agents.AI.DurableTask` is **not adopted as default** here. The `CheckpointManager` + custom `ICheckpointStore` pattern above covers the same durability need without an Azure dependency. Only reach for the Durable Task extension when a specific client already runs on Azure and needs multi-day/serverless HITL waits — record that decision in `decisions.md`.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Why it's wrong | Right way |
+|--------------|----------------|-----------|
+| Adding a `Workflow` with `RequestPort` but no `CheckpointManager` | A pending human approval is lost if the process restarts while waiting | Wire a persistent `CheckpointManager` (file-based or custom `ICheckpointStore`) whenever a HITL wait can outlive a single process lifetime |
+| Reaching for `Microsoft.Agents.AI.DurableTask` by default | Adds an Azure Durable Task Scheduler dependency this framework's VPS-first stack doesn't otherwise need | Use base `CheckpointManager` + custom `ICheckpointStore`; reserve the Durable Task extension for projects already committed to Azure |
+| Storing checkpoints in a public or unauthenticated location | Checkpoint storage is a trust boundary — a tampered checkpoint can inject arbitrary state on restore | Restrict read/write access to the checkpoint store the same way you would a secrets store |
+| Skipping `OnCheckpointingAsync`/`OnCheckpointRestoredAsync` on an executor with instance state | State silently resets to defaults after a resume, corrupting workflow logic | Any executor with fields beyond the message flow must implement both methods |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `ai-agents-workflows`' HITL or long-running criterion is documented in `decisions.md` before this standard is applied.
+- [ ] Every HITL wait point uses `RequestPort` + handles `RequestInfoEvent`.
+- [ ] A `CheckpointManager` is wired whenever the workflow can pause across a process restart — `CreateInMemory()` is acceptable only for tests/demos.
+- [ ] If a custom `ICheckpointStore` was implemented, it persists to infrastructure already owned by the project (e.g., Neon Postgres), not a new ad hoc store.
+- [ ] Executors with instance state implement `OnCheckpointingAsync` and `OnCheckpointRestoredAsync`.
+- [ ] `Microsoft.Agents.AI.DurableTask` is present only if the project already runs on Azure and the choice is recorded in `decisions.md`.
+
+---
+
+## References
+
+- `ai-agents-workflows` — when a Workflow (and therefore this standard) is justified
+- `ai-agents-sweet-spot` — single agent vs workflow decision
+- `ai-agents-multi-agent-patterns` — agent orchestrations that share the tool-approval HITL mechanism
+- `ai-agents-setup` — the VPS-first, non-Azure-default stance this standard follows for durability
+- `infrastructure-neon-setup` — Postgres connection patterns for a custom `ICheckpointStore`
+- Human-in-the-loop (HITL) | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/workflows/human-in-the-loop
+- Checkpoints | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/workflows/checkpoints
+- Durable Extension | Microsoft Learn: https://learn.microsoft.com/en-us/agent-framework/integrations/durable-extension
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/durable-workflows-hitl.md v1.0 (2026-07-06)*