systemfsoftware

                                  Input `I`
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│  Cell<in I, out A, out E, out R>                                            │
│                                                                             │
│   1. Read       (Impure: (input: I) => Effect<Encoded<Cmd>, RE, RR>)        │
│         │                                                                   │
│         ▼                                                                   │
│   2. Decode     (Pure: Schema.decodeUnknown(CommandSchema))                 │
│         │                                    │                              │
│      [valid]                             [invalid]                          │
│         │                                    │                              │
│         ▼                                    ▼                              │
│   3. Decide     (Pure: Workflow.make)    5b. Write: CommandRejected handler │
│         │                                            │                      │
│      [Result]                                        │                      │
│         │                                            │                      │
│         ▼                                            │                      │
│   4. Encode     (Pure: variant schemas)              │                      │
│         │                                            │                      │
│         ▼                                            │                      │
│   5a. Write     (Impure: Tag-keyed handlers)         │                      │
│         │                                            │                      │
└─────────┼────────────────────────────────────────────┼──────────────────────┘
          ▼                                            ▼
   Handler Response (`A`)              Infrastructure Error (`RE | WE` in `E`)

Quick Start

pnpm add 'effect@^4'

1. Declare the Pure Decision Workflow

import { Workflow } from '@systemfsoftware/effect-cell-types'
import { Match, Result, Schema as S } from 'effect'

// Family brand distinguishing this decision's variants
const AllocationTypeId: unique symbol = Symbol.for('inventory/Allocation')
type AllocationTypeId = typeof AllocationTypeId

export class AllocateStockCommand extends S.Class<AllocateStockCommand>('AllocateStockCommand')({
  orderId: S.String,
  requestedQuantity: S.Int.pipe(S.check(S.isGreaterThan(0))),
  availableQuantity: S.Int.pipe(S.check(S.isGreaterThanOrEqualTo(0))),
}) {
  static readonly [Workflow.InstrumentationBrand] = { orderId: 'app.order.id' } as const
}

export class StockAllocated extends S.TaggedClass<StockAllocated>()('StockAllocated', {
  orderId: S.String,
  quantity: S.Int,
}) {
  readonly [AllocationTypeId] = AllocationTypeId
}

export class InsufficientStockRefusal extends S.TaggedError<InsufficientStockRefusal>()('InsufficientStockRefusal', {
  orderId: S.String,
  deficit: S.Int,
}) {
  readonly [AllocationTypeId] = AllocationTypeId
}

export const allocateStockWorkflow = Workflow.make({
  command: AllocateStockCommand,
  decision: StockAllocated,
  error: InsufficientStockRefusal,
  decide: (cmd) =>
    Match.value(cmd.availableQuantity >= cmd.requestedQuantity).pipe(
      Match.when(true, () =>
        Result.succeed(
          new StockAllocated({
            orderId: cmd.orderId,
            quantity: cmd.requestedQuantity,
          }),
        )),
      Match.when(false, () =>
        Result.fail(
          new InsufficientStockRefusal({
            orderId: cmd.orderId,
            deficit: cmd.requestedQuantity - cmd.availableQuantity,
          }),
        )),
      Match.exhaustive,
    ),
})

2. Wrap in a Five-Phase Cell Sandwich

import { Cell, Sandwich } from '@systemfsoftware/effect-cell-types'
import { Context, Effect } from 'effect'
import { allocateStockWorkflow } from './allocate-stock.workflow.js'

export class InventoryStore extends Context.Service<InventoryStore, {
  readonly getAvailableStock: (sku: string) => Effect.Effect<{ readonly quantity: number }>
  readonly commitAllocation: (orderId: string, quantity: number) => Effect.Effect<void>
}>()('InventoryStore') {}

export interface OrderRequest {
  readonly orderId: string
  readonly sku: string
  readonly requestedQuantity: number
}

export const allocateStockCell = Sandwich.named('inventory.allocate')(
  // Phase 1: Read (impure) -> returns Command's Encoded shape
  (req: OrderRequest) =>
    Effect.gen(function*() {
      const inventory = yield* InventoryStore
      const stock = yield* inventory.getAvailableStock(req.sku)
      return {
        orderId: req.orderId,
        requestedQuantity: req.requestedQuantity,
        availableQuantity: stock.quantity,
      }
    }),
)
  // Phase 2 (Decode) & Phase 4 (Encode) are derived automatically from schemas
  // Phase 3: Decide (pure workflow)
  .decide(allocateStockWorkflow)
  // Phase 5: Write (impure) -> exhaustive handlers over outcomes plus CommandRejected
  .write({
    StockAllocated: ({ orderId, quantity }) =>
      Effect.gen(function*() {
        const inventory = yield* InventoryStore
        yield* inventory.commitAllocation(orderId, quantity)
        return { status: 'allocated' as const, orderId, quantity }
      }),
    InsufficientStockRefusal: ({ orderId, deficit }) =>
      Effect.succeed({ status: 'refused' as const, orderId, deficit }),
    CommandRejected: ({ issue }) => Effect.fail(new Error(`Validation failed: ${issue}`)),
  })

3. Bind Services at the Composition Root

import { Cell } from '@systemfsoftware/effect-cell-types'
import { Effect, Layer } from 'effect'
import { allocateStockCell, InventoryStore } from './allocate-stock.cell.js'

const InventoryLive = Layer.succeed(InventoryStore, {
  getAvailableStock: (_sku) => Effect.succeed({ quantity: 10 }),
  commitAllocation: (_orderId, _qty) => Effect.void,
})

const program = Effect.gen(function*() {
  const context = yield* Layer.build(InventoryLive)
  const cell = Cell.provideContext(allocateStockCell, context)

  const result = yield* cell.run({
    orderId: 'ord-123',
    sku: 'widget-a',
    requestedQuantity: 2,
  })

  return result
})

Architectural Doctrine

Install a package

{
  nixConfig = {
    extra-substituters = "https://nix.systemfsoftware.com";
    extra-trusted-public-keys = "nix-cache-1:wXA8I4DayNW9q6enUyQA/P/nT38pGSTLt374t3gsn7M=";
    fallback = true;
  };

  inputs = {
    producer.url = "github:systemfsoftware/systemfsoftware/<rev>";
    nixpkgs.follows = "producer/nixpkgs";
    pnpm-release-management.url = "github:systemfsoftware/pnpm-release-management";
  };
}

pnpm add 'effect@^4'

Packages

Core architecture

Schema and property laws

Specs and simulation

Test and build tooling

Oxlint rules and presets

In their own repositories

Roadmap: Non-Autoregressive Decisions (Jev)

Conversational LLM:
  Diff ──► [ Prompt ] ──► "Looks good to me" (Uncalibrated, non-reproducible)

System One Decision Gate:
  Diff ──► [ Jev DecisionModel ] ──► P(regression) = 0.84, Label = "breaking" (~35ms forward pass)
                 │
                 ▼
  Tri-State Evaluation:
  • >= 0.80   ──► Reject PR / require migration
  • <= 0.50   ──► Pass
  • 0.50–0.80 ──► Mark uncertain (route to human reviewer)

Reference Implementation

Documentation

Contributing

License