Triplex · The database that remembers why

The database that remembers why.

Facts change. Rules change. Your record of what happened shouldn’t.

Triplex is a bitemporal fact database that keeps facts, time, and versioned rules together in your TypeScript process. Every write records who acted, which rules applied, and when it was true. Audit questions and open work become queries instead of investigations.

npm install @triplex-build/triplex effect

Effect 4 required · MIT licensed · In-memory and SQLite supported · PostgreSQL is a production candidate · Current state

// March 2 as Dana knew it; June 1 as we know it now.const { position } = hired;const then = { recordedPosition: position, validAt: MAR_2 };const view = yield* db.asOf(then);const knownThen = yield* view.get(Worker, maria);const june = { validAt: JUN_1 };const now = yield* (yield* db.asOf(june)).get(Worker, maria);const entity = { kind: "entity", entityId: maria } as const;const why = yield* explain.why(entity, { basis: june });

Where the evidence usually lives	What it can no longer tell you
Application database	The training row was corrected in place, so the original belief is gone
Config service or repository	The placement rules have changed since. Which version applied?
Audit log	Who acted, but not the facts they saw or the rules they were held to
Job queue	Whether a training task should have existed, and when it should reopen

Where the evidence usually lives

What it can no longer tell you

Application database

The training row was corrected in place, so the original belief is gone

Config service or repository

The placement rules have changed since. Which version applied?

Audit log

Who acted, but not the facts they saw or the rules they were held to

Job queue

Whether a training task should have existed, and when it should reopen

Step 01 · Model

Declare the domain once.

Attributes own global keys and value types. Entity types declare aliases, required fields, cardinality, and reference targets. The same declarations drive command inputs and typed reads.

Typed configuration →

client.tsmodel

import { Effect, Layer } from "effect";
import { EntityId, KvTriples } from "@triplex-build/triplex";
import { Attribute, ConfigStore, EntityType } from "@triplex-build/triplex/config";
import * as Database from "@triplex-build/triplex/database";
import { Why } from "@triplex-build/triplex/why";

const Worker = EntityType.make("Worker", {
  name: Attribute.text(":worker/name").required(),
});
const Model = { types: [Worker] } as const;
const maria = EntityId.make("worker:maria");
const MAR_2 = Date.UTC(2026, 2, 2);

Step 02 · Rules

Publish the rules as a release.

The host publishes an immutable, content-addressed release before acquiring the client. Database.layer checks the model against live; every new command pins and enforces the release it admits.

Releases, refs, and rollback →

client.tsrelease

const publish = Effect.gen(function* () {
  const config = yield* ConfigStore.ConfigStore;
  return yield* config.commit({
    label: "workers-v1",
    objects: yield* EntityType.nodesOf(...Model.types),
    ref: "live",
  });
});
const Client = Database.layer({ schema: Model });

Step 03 · Command

One command, one atomic transaction.

db.command returns a persisted receipt with actor, command ID, release, and commit position. The builder’s tx.create encodes typed values and checks that the entity is new. Retrying the same command ID returns the original receipt.

Commands and receipts →

client.tscommand

const db = yield* Database.Database;
const createWorker = () =>
  db.command({ actor: "user:dana", commandId: "create:worker:maria" }, (tx) =>
    tx.create(Worker, maria, { name: "Maria" }, { validFrom: MAR_2 }),
  );
const receipt = yield* createWorker();
const retry = yield* createWorker(); // same receipt, no second write

Step 04 · Read

Read through your schema.

db.get returns alias-keyed values or null. db.list returns a bounded page and a cursor. For joins, db.query checks attributes against the release and decodes each binding with an Effect Schema projection.

Typed reads and queries →

client.tsread

const worker = yield* db.get(Worker, maria); // { entityId, values } | null
const page = yield* db.list(Worker, { limit: 25 });
// worker?.values.name is typed from Worker; page.nextCursor continues the list.

Step 05 · Audit

Keep the correction and the original belief.

tx.correct replaces a fact over its original valid interval and keeps the recorded history. db.asOf at the receipt’s exact position returns a stable, read-only view: what was known then, for the business date in question.

Recorded time and valid time →

client.tsaudit

// Correct the original belief without losing its history.
const nameFact = receipt.changes.find(
  (change) => change.op === "assert" && change.attribute === Worker.attributes.name.key,
);
if (nameFact === undefined) return yield* Effect.die("Missing name assertion");
yield* db.command({ actor: "user:auditor", commandId: "correct:worker:maria:name" }, (tx) =>
  Effect.gen(function* () {
    const fact = yield* tx.fact(Worker, nameFact.tripleId);
    yield* tx.correct(Worker, fact, { name: "Maria Rivera" });
  }),
);
const basis = { recordedPosition: receipt.position, validAt: MAR_2 };
const then = yield* db.asOf(basis);
const knownThen = yield* then.get(Worker, maria); // name: "Maria"
const current = yield* db.get(Worker, maria); // name: "Maria Rivera"

Step 06 · Explain + run

Ask why, at the same cut.

The Why service explains the visible facts, their asserting transactions, actors, and pinned releases. Pass the historical view’s basis so the explanation and typed read agree. Compose the client and explanation services over one shared store.

Explain a fact with why →

client.tswhy

const why = yield* Why;
const explanation = yield* why.why(
  { kind: "entity", entityId: maria },
  { basis }, // explain the same recorded cut and business time
);
// explanation.transactions includes Dana's command and its workers-v1 release.

One store for the application lifetimerun

const Store = ConfigStore.layer.pipe(Layer.provideMerge(KvTriples.layer));
const Services = Layer.merge(Client, Why.layer);
// Publish before acquiring the client. Both effects share one Store instance.
export const main = publish.pipe(
  Effect.andThen(program.pipe(Effect.provide(Services))),
  Effect.provide(Store),
);
// await Effect.runPromise(main) at your application boundary.
// For SQLite, import SqliteTriples from "@triplex-build/triplex/sqlite" and use
// SqliteTriples.layer({ filename: "./app.db" }) in place of KvTriples.layer.

	Event handlers that enqueue tasks	Triplex derivations
Source of truth	Whatever each handler remembered to do	A Datalog query over facts, pinned to a release
Late corrections	Missed unless someone re-runs a handler	Appear on the next evaluation, even for past dates
Expiring evidence	A separate cron job per rule	`nextTemporalBoundary` says exactly when to re-evaluate
Duplicates	Hand-built idempotency	Stable, content-addressed candidate IDs
Explanation	Log lines	Each candidate carries its source facts and assertion transactions
Change	Diff it yourself	`Derivation.reconcile` returns `added`, `removed`, and `changed`

Event handlers that enqueue tasks

Triplex derivations

Source of truth

Whatever each handler remembered to do

A Datalog query over facts, pinned to a release

Late corrections

Missed unless someone re-runs a handler

Appear on the next evaluation, even for past dates

Expiring evidence

A separate cron job per rule

nextTemporalBoundary says exactly when to re-evaluate

Duplicates

Hand-built idempotency

Stable, content-addressed candidate IDs

Explanation

Log lines

Each candidate carries its source facts and assertion transactions

Change

Diff it yourself

Derivation.reconcile returns added, removed, and changed

In your domain	In Triplex	In the example or guide
Things: workers, sites, cases, accounts	Declare an `EntityType`; create with `tx.create`	`Worker`, `worker:maria`
Properties and relationships	Typed `Attribute` keys and `Attribute.ref`	`:worker/name`
Schemas, policies, forms	Publish a release; acquire `Database.layer`	`workers-v1`
User and system actions	One `db.command` per action, with actor and stable command ID	Dana’s create command and receipt
Evidence that starts or expires	`validFrom` and `validTo` on builder writes	Maria’s facts start on March 2
Corrections and changes from a date	`tx.correct`, `tx.replace`, or `tx.end` inside a command	The auditor’s name correction
Current state and lists	`db.get`, `db.list`, and Schema-projected `db.query`	Step 04, Read
Audit questions	`db.asOf`, `db.receipt`, `db.history`, and `why.why`	Steps 05–06
Obligations and to-dos	A `Derivation` over `Triples`, with an explicit release	Modeling guide
Tickets, notifications, SLAs	Host code driven by reconciliation diffs and wake-up boundaries	Host integration

In your domain

In Triplex

In the example or guide

Things: workers, sites, cases, accounts

Declare an EntityType; create with tx.create

Worker, worker:maria

Properties and relationships

Typed Attribute keys and Attribute.ref

:worker/name

Schemas, policies, forms

Publish a release; acquire Database.layer

workers-v1

User and system actions

One db.command per action, with actor and stable command ID

Dana’s create command and receipt

Evidence that starts or expires

validFrom and validTo on builder writes

Maria’s facts start on March 2

Corrections and changes from a date

tx.correct, tx.replace, or tx.end inside a command

The auditor’s name correction

Current state and lists

db.get, db.list, and Schema-projected db.query

Step 04, Read

Audit questions

db.asOf, db.receipt, db.history, and why.why

Steps 05–06

Obligations and to-dos

A Derivation over Triples, with an explicit release

Modeling guide

Tickets, notifications, SLAs

Host code driven by reconciliation diffs and wake-up boundaries

Host integration

The database that remembers why.

What if the answer were a query?

One store, one identity model, one clock.

From schema to an answer you can explain.

Declare the domain once.

Publish the rules as a release.

One command, one atomic transaction.

Read through your schema.

Keep the correction and the original belief.

Ask why, at the same cut.

Stop enqueuing obligations. Reconcile them.

Triplex owns

Your application owns

See it end to end

From a back-office domain to client commands.

A library, not another server.

When to use Triplex, and when not to.

A good fit

Not a fit

Datomic

Current XTDB

WorldVM

Event sourcing

Workflow engines

Small experiments. Bigger worlds.