Skip to content
linuxbPublic

About

AI harness orchestration for reliable e-commerce agents.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

102 Commits

Folders and files

Repository files navigation

Flory

Event log verification Console client Formal verification Coverage

Animated Flory architecture: a planner proposes a sub-DAG against one frozen tool view; checkSubDag admits it against rules R1-R14 and the frozen subgraph is appended to the run's append-only event log; the Agent Orchestrator claims the read-only vertices and the Distributed Transaction Coordinator claims every effectful one; through gatewayd a TCC try seals a bracket on the inventory and payment services, a pivot barrier holds until every try is sealed, the irreversible logistics booking runs, txn/pivot-passed closes a one-way gate, and the sealed members confirm.

one log for the DAG and the transaction brackets  ·  the rules admit a plan, the model never does  ·  past the pivot, recovery only moves forward
diagram source: doc/animations/src

Flory is a design for an AI harness orchestration engine for AI-driven e-commerce. It supports workflows spanning supplier operations (product selection, procurement, and inventory) and sales channels (pricing, listings, orders, and logistics).

The system is designed for the difficult boundary between probabilistic LLM planning and irreversible business effects. It combines just-in-time DAG planning with append-only event logging, deterministic transaction validation, and recovery-aware execution.

Status

This repository contains the architecture and design baseline plus an executable core. The TypeScript engine on PostgreSQL implements two-plane immutable event storage, canonical projections, offline forks, the deterministic check-rules R1-R14, deterministic routers, a planner loop behind a provider-neutral model adapter, the L0-L2 levels of the recovery ladder including cancel-before-replan, and the T-A harness tests. The Distributed Transaction Coordinator and the gatewayd Tool Registry Gateway, with OIDC authentication and role-scoped tool views, are in Go 1.25, and a read-only Console draws a run as it unfolds. Five test-only tool services — inventory, payment, logistics, channel, and sourcing — register with the gateway through the SDK and exercise complex e-commerce DAG admission, router branching, barrier placement, and gateway-routed execution.

Work that is specified but not yet built — business-plane consumers, the rest of the recovery ladder, the duplicate-delivery scenario, and the next formal-verification stage — is tracked in the outstanding-work backlog. Production business adapters remain out of scope.

Architecture at a glance

  • TypeScript engine: owns the planner loop, deterministic routers, canonical context-projection pipeline, check rules, prompt assembly, refine loop, model adapters, the executor for read-only vertices, and replay testing.
  • Distributed Transaction Coordinator: owns transaction scopes, runtime barriers, timeout handling, tool execution, and business-adapter orchestration. Its current implementation uses Go 1.25.
  • gatewayd: authenticates OIDC identities, owns business-role mappings, publishes immutable role-scoped tool views, and routes exactly one requested tool call without taking ownership of planning, retries, or transaction events. It speaks authenticated MCP to executors, gRPC to tool services, and mTLS HTTP to RBAC administrators.
  • Tool-service SDK: what a tool service embeds to declare its contracts, register them, heartbeat, and serve execution. Available for Go and TypeScript from one generated contract.
  • PostgreSQL: stores both append-only event planes — run_event_log for what a run orchestrated and business_event_stream for what a business entity experienced — together with metadata-only harness state, the transaction projections and work queue, and the gateway's role bindings. It allocates run_seq within a run and stream_seq within an entity.
  • Console: a read-only TypeScript server and React client that draw one run's graph from a separately versioned projection of the same log. It reads as console_role, which may SELECT from run_event_log and nothing else, so the Console cannot write.
  • The event log is the boundary: the services do not call each other's internals. They coordinate only by appending the event types they own. Execution events belong to the vertex's executor: read-only vertices are the Orchestrator's, everything else is the Coordinator's, and the database enforces the split.

Planner thought calls use a provider-neutral adapter configured through FLORY_LLM_*. Set a complete OpenAI Chat Completions-compatible or Anthropic Messages-compatible endpoint, its exact model ID, and either FLORY_LLM_API_KEY or the safer local FLORY_LLM_API_KEY_FILE. See .env.example for the full configuration, including optional provider request fields and auditable pricing snapshots. Successful calls record measured duration, normalized provider token usage, and optional estimated cost in budget/charged; secrets and raw prompts or completions are not event payloads.

Local development

Flory needs one PostgreSQL 16-or-newer server and does not care where it comes from. All connections are derived from DATABASE_URL, so choose whichever path matches your machine; the remaining steps are identical.

Code intelligence

The repository includes project-level CodeGraph MCP configuration for Codex and Claude Code. Antigravity reads its MCP configuration from the user profile, so register it once with codegraph install --target=antigravity --location=global --yes. Other stdio MCP clients can launch sh scripts/codegraph-mcp.sh from the repository root. Restart an agent after changing its MCP configuration.

Run codegraph init once after cloning. The local SQLite graph stays under .codegraph/; only its .gitignore marker is committed. Agent MCP sessions start through scripts/codegraph-mcp.sh, which runs an incremental sync every two seconds and catches edits made by any editor or agent. Set CODEGRAPH_POLL_SECONDS to change the interval.

codegraph status
codegraph explore "how does gateway execution reach a tool service"

Using a PostgreSQL server you already run

npm run db:bootstrap provisions the Flory roles and database inside an existing server, which keeps a server shared with other projects untouched apart from those roles and that database. It needs administrative credentials once: either the standard PGUSER/PGPASSWORD environment, or an explicit FLORY_ADMIN_DATABASE_URL.

cp .env.example .env   # set DATABASE_URL if your server is not on 127.0.0.1:5432
npm ci
FLORY_ADMIN_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres npm run db:setup

db:setup runs db:bootstrap and then db:migrate. Both are idempotent. Only db:bootstrap uses the administrative connection, because roles and databases are cluster-level objects; migrations run as the owner role from DATABASE_URL and write only inside the Flory database.

Using the optional container

Contributors without a local server can start one from docker/compose.yml. The container creates the database and owner role itself, and because that owner is a superuser, db:setup needs no administrative credentials here. Data lives in the postgres_data named volume, and PostgreSQL is published only on 127.0.0.1.

cp docker/.env.example docker/.env   # optional: change the container credentials or port
npm ci
npm run db:up
npm run db:setup

Stop it with npm run db:down, which preserves the volume. To discard the local data as well, run docker compose -f docker/compose.yml down -v.

Local OIDC and RBAC

The local identity provider is Keycloak, but it contains no business roles or role mapper. Its short-lived tokens prove only a stable (issuer, subject) and the configured audience. Business roles and bindings are created through the Gateway's mTLS administration API and stored in PostgreSQL.

npm run db:up
npm run db:setup
npm run rbac:pki
npm run oidc:up

The generated CA, service certificates, and Ed25519 keyring live under the gitignored .cache/rbac-e2e/ directory. The local issuer is http://127.0.0.1:8180/realms/flory; insecure HTTP is a local-test exception and production configuration accepts HTTPS only. Run npm run test:rbac for the complete revoke-and-resume scenario, and stop Keycloak with npm run oidc:down.

gatewayd enables RBAC by default and therefore refuses to start without its OIDC, PostgreSQL, signing-key, and TLS configuration. scripts/e2e-up.mjs explicitly disables RBAC only for the older contract-routing fixture; it is not a production deployment example.

Verifying

npm run verify
go -C coordinator test ./...
go -C gatewayd test ./...

The Coordinator integration tests run against the same flory_test database, so run npm run verify (or npm test) once first to provision it. Before the suite starts, a TestMain empties the work queue, clears pending cancellation requests and sets aside any scope a previous run left open — only on a database whose name ends in _test:

FLORY_INTEGRATION=1 go -C coordinator test ./...

ENGINE_DATABASE_URL and COORDINATOR_DATABASE_URL still point them elsewhere, and OWNER_DATABASE_URL names the owner connection the reset uses.

npm run verify uses a database of its own. On first run it provisions <your database>_test with the same bootstrap and migrations, and it empties the work queue before every run. Nothing it does touches the development database, and nothing running against that database disturbs it — so a Coordinator or a demo left open in another terminal is no longer a reason for a test to fail. Point FLORY_TEST_DATABASE_URL somewhere else to override it.

That isolation matters because work_queue is global by design: one worker pool serves every run, so any process claiming from it is a competing worker. A live Coordinator would claim the very vertex a leasing test had just enqueued, and the test would fail on an assertion about leasing rather than about whatever had actually broken.

The Go suites still share the development database and still leave unfinished work behind, so they expect an empty one. Refresh before each:

npm run db:refresh && go -C coordinator test ./...   # with the two URLs exported as above

Coverage

Every suite can report the code it ran. Each command prints a summary and writes a report:

npm run test:coverage                     # engine, TypeScript SDK, Console server → coverage/index.html
npm -C console/client run test:coverage   # Console client → console/client/coverage/index.html
go -C coordinator test -coverpkg=./... -coverprofile=coverage.out ./...
go -C coordinator tool cover -html=coverage.out   # the same two commands work for gatewayd

CI measures the same suites against a real PostgreSQL, with FLORY_INTEGRATION=1, and uploads each one to Codecov under its own flag. A local Go run without the integration environment skips the database scenarios, so it reports less than CI does.

Component Coverage Measured by
Engine, TypeScript SDK, and Console server engine npm run verify:coverage in event-log.yml
Distributed Transaction Coordinator coordinator go test -coverpkg=./... in event-log.yml
Tool Registry Gateway gatewayd go test -coverpkg=./... in event-log.yml
Console client console-client npm run verify:coverage in console.yml

Coverage is report-only: it is shown on every commit and pull request and never fails a check. Each workflow runs only when its own paths change, so a flag that did not run keeps its last value rather than dropping out of the total. codecov.yml holds those rules and what is not counted: generated code, process entries (cmd/ and console/server/src/main.ts), db/ and scripts/ (which the suites reach through child processes), and the RBAC and gateway end-to-end suites, which drive separately started processes. The engine's HTML report is also kept on each event-log.yml run as the engine-coverage-report artifact for 14 days.

Running the gateway-mediated topology

Every tool call goes through gatewayd. npm run e2e:up brings the topology up in dependency order — the gateway, then the five mock tool services, which register themselves through the SDK — and finishes once the gateway reports a published tool view:

npm run e2e:up

It defaults to in-memory tool-view storage, which needs nothing installed but loses every published view on restart. To use a GCS-compatible store instead, point it at an emulator:

docker run -d --rm -p 4443:4443 fsouza/fake-gcs-server -scheme http -public-host localhost:4443
STORAGE_EMULATOR_HOST=http://localhost:4443 GATEWAYD_BLOB_BACKEND=gcs npm run e2e:up

STORAGE_EMULATOR_HOST must match the emulator's -public-host. When it does not, writes land but reads resolve to nothing, which looks like an empty bucket rather than a misconfiguration.

With the topology up, GATEWAY_BASE_URL=http://127.0.0.1:8092 npx vitest run test/conformance/gateway-e2e.test.ts exercises the live path, and npm run record:tool-view refreshes the recorded view the check-rule fixtures read. Then run the Coordinator with go -C coordinator run ./cmd/coordinator; its health endpoints default to 127.0.0.1:8091. Production business adapters are intentionally not included.

Watching a run recover

npm run demo:retail takes an optional fault, so the run hits a real failure and the recovery ladder has something to do:

FLORY_DEMO_FAULT=inventory.check npm run demo:retail

The named tool then fails every attempt, scheduled through the sandbox's own fault table, so the engine learns about it exactly as it would learn about an outage. The run shadows the discarded subtree, calls the chosen planner again with the failure as evidence, and continues in the same run — and the console draws what was abandoned beside what replaced it.

Watching a run in the console

The console is read-only and reads the log as console_role, which npm run db:setup creates. Start the API and the client:

npm run console
npm run dev --prefix console/client

The API binds 127.0.0.1:8094 and refuses any other address unless CONSOLE_ALLOW_REMOTE=true, because who may read a run is still an open question (doc 11 §7). The client serves http://localhost:5173 and proxies /api to it, so the API needs no CORS headers. Open a run at #/run/<run-id>, or pick one from the list.

To work on the client without a database, replay a captured run instead:

npm run console:mock
npm run dev:mock --prefix console/client

npm run console:capture -- <run-id> records a fresh fixture through the server's own projector, so what the mock replays is the real wire format rather than an approximation of it.

The default connection string is postgresql://flory:flory-dev-password@127.0.0.1:5432/flory. Confirm access with:

psql postgresql://flory:flory-dev-password@127.0.0.1:5432/flory -c 'SELECT version();'

Design guarantees

  • The event log is ground truth: rows are append-only, and changed or replanned state is represented by new events.
  • Planner-context projections are pure, deterministic, and implemented exactly once in TypeScript.
  • Transaction safety is enforced by deterministic check rules; model self-review is never the authority.
  • A pivot is a one-way gate: after an irreversible effect, recovery proceeds forward and never automatically compensates backward.
  • Harness state stores versioned metadata only. Prompt prose and raw memory live outside it.
  • Offline evaluations are reproducible from the recorded source position, substitutions, fold mode, evaluator pin, projector version, and harness-state version.

Documentation

Start with the design overview. The design series then covers:

Document Focus
JIT DAG and event log DAG model, event schema, projections, in-place replanning, and offline forks.
Transaction model TCC, pivot-saga, transaction boundaries, and check rules.
Replanning and recovery Failure handling, backtracking, rollback, and budget control.
Refine and harness state Structured refinement, metadata-only state, and memory hints.
Context aggregation and offline evaluation Canonical projections, semantic folds, replay, and historical evaluation.
Validation harness Sandbox contract, fault injection, scenario matrix, and correctness oracles.
Distributed Transaction Coordinator Scope lifecycle, event-log interactions, barriers, execution, and recovery.
Database schema and storage model Event log immutability, sequence allocation, and synchronous projections.
gatewayd Tool Registry Gateway Immutable tool views, dynamic registration, the SDK, and one-attempt routing.
Deterministic routers Router vertices, rule templates, freeze-time admission, and zero-model branching.
Console and observability The observability projection, SSE streaming, the operator views, and the read-only boundary.

The README hero image is the animated architecture overview; its generator lives in doc/animations/src. Architecture diagrams are available in doc/diagram/. The deployment architecture is the current deployment view; the conceptual architecture overview remains a higher-level companion. Router admission is the self-contained companion to the router design and the reference implementation of the diagram style. Editable Draw.io diagrams cover transaction boundaries, replanning, projections, and Coordinator/Engine interaction. The Console's intended look is mocked up in doc/ui-mockups/.

Repository layout

.
├── .claude/               # Claude Code instructions and CodeGraph permissions
├── .codegraph/            # Local CodeGraph index directory; database files stay ignored
├── .codex/                # Project-level Codex MCP configuration
├── .github/               # Repository automation and CI workflows
├── .mcp.json              # Project-level Claude Code MCP server registration
├── .vscode/               # Shared VS Code workspace settings: line-length rulers at 100 and 150
├── .env.example           # Overrideable local connection and service settings
├── AGENTS.md              # Contributor index, development rules, and review routes
├── codecov.yml            # Coverage flags, carryforward, and report-only status for Codecov
├── codegraph.json         # CodeGraph indexing exclusions for generated and cached content
├── console/               # Read-only operator console
│   ├── dev/               # Fixture capture and a zero-dependency mock server
│   ├── server/src/        # projection/ (the pure fold), stream/ (SSE and the tail), and the process
│   └── client/src/        # React canvas, inspector, and the one file that imports server types
├── coordinator/           # Go 1.25 Distributed Transaction Coordinator service
├── gatewayd/              # Go 1.25 Tool Registry Gateway and its Go tool-service SDK
├── db/                    # PostgreSQL migrations, bootstrap, and migration utilities
├── docker/                # Optional containerized PostgreSQL for local development
├── doc/
│   ├── adr/               # Architecture decision records
│   ├── animations/        # Animated architecture diagram and its generator
│   ├── design/            # Architecture and mechanism specifications
│   ├── diagram/           # HTML and Draw.io diagrams
│   ├── plan/              # Backlog of specified-but-undelivered work
│   └── ui-mockups/        # Visual mockups of the Console
├── spec/                  # TLA+ transaction-protocol model and TLC configurations
├── engine/                # TypeScript core
│   └── src/               # log/, admission/, planner/, router/, gateway/, harness/, and the loops
├── idl/                   # Versioned shared contracts: the event-log JSON Schema and the gateway protobufs
├── scripts/               # Code generation, style checks, the e2e topology launcher, and the demos
├── sdk/                   # TypeScript tool-service SDK
├── package.json           # Node 22 scripts and dependencies
├── test/                  # Test-only mocks, domain fixtures, and validation helpers
├── .editorconfig          # Shared editor behavior
└── .gitignore             # Go and TypeScript generated artifacts

Contributing

Read AGENTS.md before proposing implementation work. In particular:

  • Keep repository documentation in English and use the established document locations.
  • Propose and accept an ADR before implementing a large architecture change; then merge the accepted content — rejected alternatives included — into the authoritative design documents and remove every reference to the accepted ADR.
  • Treat the event log as immutable ground truth.
  • Preserve the TypeScript-only canonical projection pipeline.
  • Add a replay test whenever planner, projection, or fold behavior changes.

About

AI harness orchestration for reliable e-commerce agents.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages