FabricOrg.Platform 1.0.0

FabricOrg.Platform

A governance kernel for .NET that enforces a single, auditable mutation pipeline for every domain state change. Every write flows through one canonical door (IActionRuntime.InvokeAsync), producing an immutable audit trail of ActionInvocation, PolicyEvaluation, and AssetEvent records.

This is the .NET-native port of the TypeScript @fabricorg/platform governance framework. It targets .NET Standard 2.1 for broad compatibility and integrates seamlessly with Microsoft Orleans, ASP.NET Core, and vanilla .NET applications.

Packages

Quick Start

1. Install Packages

dotnet add package FabricOrg.Platform
dotnet add package FabricOrg.Platform.DependencyInjection
dotnet add package FabricOrg.Platform.FluentValidation
dotnet add package FabricOrg.Platform.Analyzers  # Dev dependency

2. Define a Module

public class LendingModule : IFabricModule<AppDbContext>
{
    public string Namespace => "lending";
    public string DisplayName => "Lending";

    public IReadOnlyList<ActionDefinition<AppDbContext>> Actions => new[]
    {
        new ActionDefinition<AppDbContext>
        {
            ActionId = ActionId.Parse("lending.accept_offer"),
            Namespace = "lending",
            Version = 1,
            Schema = new FluentValidationSchemaValidator(new AcceptOfferValidator()),
            Handler = AcceptOfferHandler.ExecuteAsync,
            RequiredRoles = new[] { "loan_consultant", "underwriter" },
            RequiredPermissions = new[] { "lending.offer.accept" },
            EmitsEvents = new[] { "OfferAccepted", "StateTransitioned" },
            Idempotent = true,
            MutatesDomain = true,
            StateMachine = new ActionStateMachineBinding(
                EntityType: "Offer",
                TargetStateResolver: p => "accepted",
                EntityIdResolver: p => ((AcceptOfferCommand)p).OfferId)
        }
    };

    public IReadOnlyList<StateMachineDefinition> StateMachines => new[]
    {
        new StateMachineDefinition(
            EntityType: "Offer",
            States: new Dictionary<string, StateDefinition>
            {
                ["generated"] = new("generated", "Generated", StateClass.Initial),
                ["presented"] = new("presented", "Presented", StateClass.Active),
                ["accepted"] = new("accepted", "Accepted", StateClass.Terminal),
                ["declined"] = new("declined", "Declined", StateClass.Terminal),
                ["expired"] = new("expired", "Expired", StateClass.Terminal)
            },
            Transitions: new[]
            {
                new StateTransition("generated", "presented", ActionId.Parse("lending.present_offer")),
                new StateTransition("presented", "accepted", ActionId.Parse("lending.accept_offer")),
                new StateTransition("presented", "declined", ActionId.Parse("lending.decline_offer")),
                new StateTransition("presented", "expired", ActionId.Parse("lending.expire_offer"))
            })
    };

    // ... policies, events, adapters
}

3. Register in Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFabricGovernance<AppDbContext>(options =>
{
    options.ValidateModulesOnStartup = true;
    options.EnforceBoundaryChecks = true;
});

builder.Services.AddFabricModule(new LendingModule());

// Optional: override with Orleans, Temporal, etc.
// builder.Services.WithSagaOrchestrator<TemporalSagaOrchestrator>();
// builder.Services.WithAsyncJobDispatcher<TemporalJobDispatcher>();

var app = builder.Build();

4. Invoke an Action

public class OffersController : ControllerBase
{
    private readonly IActionRuntime _runtime;
    private readonly AppDbContext _db;

    public OffersController(IActionRuntime runtime, AppDbContext db)
    {
        _runtime = runtime;
        _db = db;
    }

    [HttpPost("{offerId}/accept")]
    public async Task<IActionResult> Accept(string offerId)
    {
        var result = await _runtime.InvokeAsync(new InvokeActionRequest(
            ActionId.Parse("lending.accept_offer"),
            new Dictionary<string, object?> { ["offerId"] = offerId },
            User.Identity.Name!,
            ActorType.NaturalPerson,
            tenantId: "tenant_123",
            spaceId: "space_456"
        ), _db);

        return result.Status == ActionStatus.Completed
            ? Ok(result)
            : BadRequest(result);
    }
}

5. Orleans Integration

public class OfferGrain : GovernedGrain<IOfferRepository>, IOfferGrain
{
    public OfferGrain(IActionRuntime runtime, IOfferRepository db) : base(runtime, db) { }

    public async Task<Result> AcceptAsync(AcceptOfferCommand command, ActorContext actor)
    {
        var result = await InvokeActionAsync(new InvokeActionRequest(
            ActionId.Parse("lending.accept_offer"),
            command.ToDictionary(),
            actor.ActorId,
            actor.ActorType,
            actor.TenantId,
            actor.SpaceId
        ));

        return result.Status == ActionStatus.Completed
            ? Result.Success()
            : Result.Failure(result.Error);
    }
}

Architecture

┌─────────────────────────────────────────────────────────────┐
│  SaaS UI  │  Borrower Portal  │  Temporal Cron  │  Agent   │
└────┬────────────┬─────────────────┬───────────────┬─────────┘
     │            │                 │               │
     │  natural_person   external_system   system    agent
     │            │                 │               │
     ▼            ▼                 ▼               ▼
┌─────────────────────────────────────────────────────────────┐
│              API Layer (Host Application)                   │
│  • IActionRuntime.InvokeAsync                               │
│  • IActionRuntime.PreviewAsync                              │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │  FabricOrg.Platform Runtime   │
         │  - Module entitlement check   │
         │  - Permission check (HITL)    │
         │  - Create ActionInvocation    │
         │  - Policy evaluation          │
         │  - State machine validation   │
         │  - Execute handler (TDb txn)  │
         │  - Append AssetEvent          │
         │  - Execute adapters           │
         └───────────────────────────────┘
                         │
                         ▼
         ┌───────────────────────────────┐
         │  Vertical Handlers (lending)  │
         │  e.g. acceptOfferHandler      │
         └───────────────────────────────┘

Governance Capabilities

• Single Mutation Path — All domain writes flow through IActionRuntime.InvokeAsync. Boundary analyzers enforce this at compile time.
• Policy Engine — Code policies (C# evaluators), data policies (declarative condition trees), and hybrid policies with full PolicyDispatchEvidence audit.
• State Machines — Declarative transition graphs with guards. Invalid transitions are blocked before handlers run.
• Audit Trail — Immutable ActionInvocation, PolicyEvaluation, and AssetEvent records with correlation IDs.
• Adapter Orchestration — Retry, circuit breaker, and dead-letter queue for external service calls.
• Agent HITL — Human-in-the-loop policy routing for AI agents (auto-execute, needs-approval, escalate, rejected).
• Privacy & Redaction — Field-level redaction rules, data classification, retention policies, and anonymization.
• Evidence Packets — Curated compliance bundles linking actions, events, policies, and external documents.
• Projections — Deterministic event replay with snapshot support.
• Telemetry — System.Diagnostics.ActivitySource spans for distributed tracing.

Repository Structure

FabricOrg.Platform/
├── src/
│   ├── FabricOrg.Platform/                        # Core runtime
│   ├── FabricOrg.Platform.Abstractions/           # Contracts
│   ├── FabricOrg.Platform.DependencyInjection/    # DI extensions
│   ├── FabricOrg.Platform.FluentValidation/       # Validation bridge
│   ├── FabricOrg.Platform.Orleans/                # Orleans integration
│   ├── FabricOrg.Platform.Polly/                  # Resilience
│   ├── FabricOrg.Platform.Policies.OpenPolicyAgent/ # OPA
│   └── FabricOrg.Platform.Sdk/                    # HTTP SDK
├── analyzers/
│   └── FabricOrg.Platform.Analyzers/              # Roslyn analyzers
├── tests/
│   ├── FabricOrg.Platform.Tests/
│   ├── FabricOrg.Platform.IntegrationTests/
│   ├── FabricOrg.Platform.Orleans.Tests/
│   └── FabricOrg.Platform.Sdk.Tests/
├── samples/
│   ├── MinimalVertical/                           # Console app demo
│   ├── OrleansVertical/                           # Orleans silo demo
│   └── AgentSdkSample/                            # External agent demo
├── docs/
│   ├── architecture/
│   ├── api/
│   └── migration-from-typescript.md
└── PLAN.md                                         # Implementation plan

Building

dotnet build

Testing

dotnet test

Samples

See the samples/ directory for working examples:

• MinimalVertical — Console application with EF Core + in-memory database
• OrleansVertical — Orleans silo with governed grains
• AgentSdkSample — External agent using the HTTP SDK

License

MIT