app.ts · {{ stack.total }} lines from schema to REST API
+ Pre-1.0 · MIT licensed · In-memory + SQLite supported
PostgreSQL is a production candidate · Current state ↗
01 / One scenario, start to finish
-Maria is trained for Harbor from March 1 to June 1 and placed there on March 2 under release hr-2026.1. The rules then change: hr-2026.2 requires a supervisor on every placement. Later, an auditor finds that the certificate actually began on March 5.
Every snippet is type-checked. Every output is produced by running this scenario in CI. The database’s own journal reads:
+01 / The whole stack, top to bottom
+Model, versioned rules, a command, an audit, open work, storage, and HTTP. Each block below is the next region of the same file, in order. Every block is type-checked, and CI runs the file to produce every output on this page.
+The story: Maria is trained for Harbor from March 1 to June 1 and placed there on March 2 under release hr-2026.1. The rules then change: hr-2026.2 requires a supervisor. Later, an auditor finds that the certificate actually began on March 5.
01 · Model
+Attributes are global, typed facts. Entity types say how each one is used: required, cardinality, and references.
+Changing the rules means a new version of the type, not a migration. Old facts stay valid under the release that accepted them.
+Typed configuration +02 · Rules
+A release is immutable and content-addressed. The story publishes hr-2026.1 with Placement, then hr-2026.2 with PlacementV2. Each time, live moves and every earlier release stays exactly as it was.
00 · Record
+03 · Command
Dana’s placement records who acted, a command ID that makes retries safe, a correlation ID, and the release that governed the write. The constraints come from that same release and are checked in the same transaction.
-Nothing is overwritten. The auditor’s correction retracts the old belief and asserts the new one, and the journal keeps both.
+Dana’s placement records who acted, a command ID that makes retries safe, and the release whose constraints were checked in the same transaction.
+Under hr-2026.2, the same command is rejected. It writes no facts, no receipt, and no journal entry.
The same command under hr-2026.2
02 / Three questions, three queries
-Each answer below is the real output of the code beside it.
+After the whole story, the journal reads
+Nothing is overwritten. The auditor’s correction at position 6 retracts the old belief and asserts the new one, and the journal keeps both. The rest of the story is in story.ts.
01 · What did we know?
-validAt is the day in question. recordedAt is the instant of Dana’s receipt. At that instant, the record said Maria was trained. Today, after the correction, it says she was not.
Both answers can be proven. Dana acted in good faith on a record that was later corrected.
+04 · Audit
+validAt is the day in question. recordedAt is the instant of Dana’s receipt. At that instant, the record said Maria was trained. After the correction, it says she was not.
Both answers can be proven, and the receipt still points at hr-2026.1 even though live has moved.
Output
-<<< @/snippets/home/site-safety/output/what-we-knew.json +<<< @/snippets/home/site-safety/output/audit.json02 · Which rules applied?
-The live ref has moved to hr-2026.2, but Dana’s placement still points at hr-2026.1, the content-addressed release that governed it.
The same kind of command under today’s rules is rejected atomically. The rejected command writes no facts, no receipt, and no journal entry.
-Releases, refs, and rollback +05 · Open work
+The obligation is a Datalog query, not a queue. On March 3, the corrected record exposes a gap. On April 1, nothing is open. On June 1, the training expires and the task reopens, even though nobody wrote anything.
+recheckAt comes from nextTemporalBoundary. Schedule a wake-up for it instead of polling.
Output
- -<<< @/snippets/home/site-safety/output/which-rules.json +Evaluated on March 3, April 1, and June 1
-The same command under hr-2026.2
03 · What needs to happen?
-The obligation is a Datalog derivation: a placed worker without current training for that site.
-On March 3, the corrected record exposes a gap, so the task is open. On April 1 nothing is open, and the evaluation reports when that can next change. On June 1 the training expires and the task reopens, even though nobody wrote anything.
-recheckOn comes from nextTemporalBoundary. Schedule a wake-up for that date instead of polling.
06 · Storage + HTTP
+Storage is a layer. The same program runs in memory for tests and the browser, on SQLite, or on PostgreSQL.
+EntityHttp serves the live release as REST routes with OpenAPI docs. Every read accepts both clocks, so the audit question works over HTTP too.
Output for March 3, April 1, and June 1
+Launch it
-<<< @/snippets/home/site-safety/output/open-work.json +<<< @/snippets/home/site-safety/serve.ts + +GET /api/rest/latest/workers/worker:maria?validAt=…, with and without recordedAt
03 / Derived work
+02 / Derived work
Most back-office bugs come down to a task that should exist but doesn’t, or one that exists but shouldn’t. Event handlers create work one step at a time and drift out of sync with the data. A derivation states what should be true, and reconciliation reports the difference.
04 / Modeling
+03 / Modeling
Most back-office systems are built from the same parts. This is where each part goes.
05 / Deployment
+04 / Deployment
Triplex runs inside your process as Effect layers. Switching storage changes the layer you provide, and the rest of the program stays the same. On PostgreSQL, Triplex can share your application’s transaction, so your own rows, Triplex facts, the journal, and an outbox row commit or roll back together.
+Triplex runs inside your process as Effect layers. Switching storage changes the layer you provide, as in step 06, and the rest of the program stays the same. On PostgreSQL, Triplex can share your application’s transaction, so your own rows, Triplex facts, the journal, and an outbox row commit or roll back together.
06 / Fit
+05 / Fit
07 / Part of the WorldVM family
+06 / Part of the WorldVM family
Small experiments in software you can inspect, explain, and build on. Triplex keeps the facts. These projects explore the language and models around them.
diff --git a/docs/snippets/home/layers.ts b/docs/snippets/home/layers.ts deleted file mode 100644 index 3d0259e..0000000 --- a/docs/snippets/home/layers.ts +++ /dev/null @@ -1,16 +0,0 @@ -import { Layer } from "effect"; -import { KvTriples } from "@triplex-build/triplex"; -import { ConfigStore } from "@triplex-build/triplex/config"; -import { PgTriples } from "@triplex-build/triplex-postgres"; -import { SqliteTriples } from "@triplex-build/triplex-sqlite"; - -// The same program runs against any of these. Only the provided layer changes. -export const InMemory = ConfigStore.layer.pipe(Layer.provideMerge(KvTriples.layer)); - -export const Sqlite = ConfigStore.layer.pipe( - Layer.provideMerge(SqliteTriples.layer({ filename: "app.db" })), -); - -export const Postgres = ConfigStore.layer.pipe( - Layer.provideMerge(PgTriples.layerFromUrl(process.env["DATABASE_URL"] ?? "")), -); diff --git a/docs/snippets/home/site-safety/app.ts b/docs/snippets/home/site-safety/app.ts new file mode 100644 index 0000000..2884563 --- /dev/null +++ b/docs/snippets/home/site-safety/app.ts @@ -0,0 +1,168 @@ +/** + * The homepage site-safety application, top to bottom: model, rules, a command, + * audit questions, derived work, storage, and HTTP. The homepage shows each + * region in order, and `run.ts` executes it in CI to produce every output. + */ +import { createServer } from "node:http"; + +import { NodeHttpServer } from "@effect/platform-node"; +import { Effect, Layer } from "effect"; +import { HttpRouter } from "effect/http"; +import { EntityId, KvTriples, Triples, type TemporalBasis } from "@triplex-build/triplex"; +import { + Attribute, + ConfigStore, + ContentId, + EntityType, + GraphConstraint, + type InMemoryConfigStore, +} from "@triplex-build/triplex/config"; +import * as Derivation from "@triplex-build/triplex/derivation"; +import { EntityHttp, HttpAuthorizationAllowAll } from "@triplex-build/triplex-http"; +import { PgTriples } from "@triplex-build/triplex-postgres"; +import { SqliteTriples } from "@triplex-build/triplex-sqlite"; + +export const MAR_2 = Date.UTC(2026, 2, 2); +export const maria = EntityId.make("worker:maria"); +export const harbor = EntityId.make("site:harbor"); + +// #region model +// Attributes are global facts. Entity types say how each one is used. +export const Site = EntityType.make("Site", { + attributes: { name: Attribute.use(Attribute.text(":site/name"), { required: true }) }, +}); + +export const Worker = EntityType.make("Worker", { + attributes: { + name: Attribute.use(Attribute.text(":worker/name"), { required: true }), + trainedFor: Attribute.use(Attribute.ref(":worker/trained-for", Site), { cardinality: "many" }), + }, +}); + +const placement = { + worker: Attribute.use(Attribute.ref(":placement/worker", Worker), { required: true }), + site: Attribute.use(Attribute.ref(":placement/site", Site), { required: true }), +}; +export const Placement = EntityType.make("Placement", { attributes: placement }); + +// The next version of the rules: every placement needs a supervisor. +export const PlacementV2 = EntityType.make("Placement", { + attributes: { + ...placement, + supervisor: Attribute.use(Attribute.text(":placement/supervisor"), { required: true }), + }, +}); +// #endregion model + +// #region release +// Publishing a model creates an immutable, content-addressed release and moves `live` to it. +export const publish = (label: string, types: ReadonlyArray<{ nodes: typeof Site.nodes }>) => + Effect.gen(function* () { + const config = yield* ConfigStore.ConfigStore; + const objects = yield* Effect.all(types.map((type) => type.nodes)); + return yield* config.commit({ label, objects: objects.flat(), ref: "live" }); + }); +// #endregion release + +// #region command +// One command is one atomic transaction: who acted, which command, under which rules. +export const placeWorker = ( + release: InMemoryConfigStore.ConfigSnapshot, + placement: EntityId, + worker: EntityId, + site: EntityId, +) => + Effect.gen(function* () { + const triples = yield* Triples; + const assert = { op: "assert", entityId: placement, entityType: "Placement" } as const; + return yield* triples.transact( + [ + { ...assert, ...Placement.worker.assertion(worker, { validFrom: MAR_2 }) }, + { ...assert, ...Placement.site.assertion(site, { validFrom: MAR_2 }) }, + ], + { + actor: "user:dana", + commandId: `create:${placement}`, // unique: a retry can never apply twice + correlationId: "request:7f3a", + configSnapshot: release.id, // the rules this write answered to + enforce: GraphConstraint.enforcement(yield* GraphConstraint.collect(release.root)), + }, + ); + }); +// #endregion command + +// #region ask +// Who placed Maria, under which rules, and was she trained, as known then and now? +export const audit = Effect.gen(function* () { + const triples = yield* Triples; + const config = yield* ConfigStore.ConfigStore; + const receipt = yield* triples.transactionByCommand("create:placement:maria-harbor"); + if (receipt === null || !ContentId.isContentId(receipt.configSnapshot)) { + return yield* Effect.die("placement was not pinned to a release"); + } + + const trained = (basis: TemporalBasis) => + triples + .match({ entityId: maria, attribute: Worker.trainedFor.key }, basis) + .pipe(Effect.map((facts) => facts.length > 0)); + + return { + actor: receipt.actor, + governedBy: (yield* config.snapshotById(receipt.configSnapshot))?.label, + liveToday: (yield* config.resolveRef("live"))?.label, + trainedAsKnownThen: yield* trained({ validAt: MAR_2, recordedAt: receipt.instant }), + trainedAsKnownNow: yield* trained({ validAt: MAR_2 }), + }; +}); +// #endregion ask + +// #region derive +// Open work is a query: a placed worker without current training for that site. +export const openWork = (configSnapshot: string, validAt: number) => + Effect.gen(function* () { + const training = yield* Derivation.make({ + name: "task.site-safety-training", + query: { + find: ["?worker", "?site"], + where: [ + ["?placement", Placement.worker.key, "?worker"], + ["?placement", Placement.site.key, "?site"], + ["not", ["?worker", Worker.trainedFor.key, "?site"]], + ], + }, + identity: ["?worker", "?site"], + configSnapshot, + }); + const { candidates, nextTemporalBoundary } = yield* Derivation.evaluate( + yield* Triples, + training, + { basis: { validAt } }, + ); + return { + open: candidates.map((task) => task.result), + recheckAt: nextTemporalBoundary === undefined ? null : new Date(nextTemporalBoundary), + }; + }); +// #endregion derive + +// #region run +// The same program runs on any storage. Only the layer changes. +export const InMemory = ConfigStore.layer.pipe(Layer.provideMerge(KvTriples.layer)); +export const Sqlite = ConfigStore.layer.pipe( + Layer.provideMerge(SqliteTriples.layer({ filename: "app.db" })), +); +export const Postgres = ConfigStore.layer.pipe( + Layer.provideMerge(PgTriples.layerFromUrl("postgres://localhost/app")), +); + +// The `live` release is also a REST API with OpenAPI docs and as-of reads. +export const Api = EntityHttp.layer({ + docs: true, + exposure: { collections: { Worker: "workers", Placement: "placements" } }, +}).pipe(Layer.provide(HttpAuthorizationAllowAll)); // bring your own auth in production + +export const Server = HttpRouter.serve(Api).pipe( + Layer.provide(Sqlite), + Layer.provide(NodeHttpServer.layer(createServer, { port: 3000 })), +); +// #endregion run diff --git a/docs/snippets/home/site-safety/model.ts b/docs/snippets/home/site-safety/model.ts deleted file mode 100644 index 0dfa0d8..0000000 --- a/docs/snippets/home/site-safety/model.ts +++ /dev/null @@ -1,52 +0,0 @@ -import { Effect } from "effect"; -import { EntityId } from "@triplex-build/triplex"; -import { Attribute, ConfigStore, EntityType } from "@triplex-build/triplex/config"; - -// Attributes own global identity and value type. -export const SiteName = Attribute.text(":site/name"); -export const Site = EntityType.make("Site", { - attributes: { name: Attribute.use(SiteName, { required: true, unique: true }) }, -}); - -export const WorkerName = Attribute.text(":worker/name"); -export const TrainedFor = Attribute.ref(":worker/trained-for", Site); -export const Worker = EntityType.make("Worker", { - attributes: { - name: Attribute.use(WorkerName, { required: true }), - trainedFor: Attribute.use(TrainedFor, { cardinality: "many" }), - }, -}); - -export const PlacementWorker = Attribute.ref(":placement/worker", Worker); -export const PlacementSite = Attribute.ref(":placement/site", Site); -export const Placement = EntityType.make("Placement", { - attributes: { - worker: Attribute.use(PlacementWorker, { required: true }), - site: Attribute.use(PlacementSite, { required: true }), - }, -}); - -// hr-2026.2 changes the rules: every placement now needs a supervisor. -export const PlacementSupervisor = Attribute.text(":placement/supervisor"); -export const PlacementV2 = EntityType.make("Placement", { - attributes: { - worker: Attribute.use(PlacementWorker, { required: true }), - site: Attribute.use(PlacementSite, { required: true }), - supervisor: Attribute.use(PlacementSupervisor, { required: true }), - }, -}); - -export const maria = EntityId.make("worker:maria"); -export const harbor = EntityId.make("site:harbor"); -export const placement = EntityId.make("placement:maria-harbor"); - -// Entity types own usage rules. Publishing them creates an immutable release. -export const publish = (label: string, placementType: typeof Placement | typeof PlacementV2) => - Effect.gen(function* () { - const config = yield* ConfigStore.ConfigStore; - return yield* config.commit({ - label, - objects: [...(yield* Site.nodes), ...(yield* Worker.nodes), ...(yield* placementType.nodes)], - ref: "live", - }); - }); diff --git a/docs/snippets/home/site-safety/open-work.ts b/docs/snippets/home/site-safety/open-work.ts deleted file mode 100644 index 6d9322b..0000000 --- a/docs/snippets/home/site-safety/open-work.ts +++ /dev/null @@ -1,37 +0,0 @@ -import { Effect } from "effect"; -import { Triples } from "@triplex-build/triplex"; -import * as Derivation from "@triplex-build/triplex/derivation"; -import { PlacementSite, PlacementWorker, TrainedFor } from "./model.ts"; - -// Obligation: every placed worker holds current training for that site. -export const siteSafety = (configSnapshot: string) => - Derivation.make({ - name: "task.site-safety-training", - query: { - find: ["?worker", "?site"], - where: [ - ["?placement", PlacementWorker.key, "?worker"], - ["?placement", PlacementSite.key, "?site"], - ["not", ["?worker", TrainedFor.key, "?site"]], - ], - }, - identity: ["?worker", "?site"], - configSnapshot, - }); - -const day = (instant: number) => new Date(instant).toISOString().slice(0, 10); - -// Which training tasks should be open on a given day, and when will that change? -export const openWorkOn = (configSnapshot: string, validAt: number) => - Effect.gen(function* () { - const triples = yield* Triples; - const definition = yield* siteSafety(configSnapshot); - const { candidates, nextTemporalBoundary } = yield* Derivation.evaluate(triples, definition, { - basis: { validAt }, - }); - return { - on: day(validAt), - open: candidates.map((task) => task.result), - recheckOn: nextTemporalBoundary === undefined ? null : day(nextTemporalBoundary), - }; - }); diff --git a/docs/snippets/home/site-safety/output/audit.json b/docs/snippets/home/site-safety/output/audit.json new file mode 100644 index 0000000..ff0fffc --- /dev/null +++ b/docs/snippets/home/site-safety/output/audit.json @@ -0,0 +1,7 @@ +{ + "actor": "user:dana", + "governedBy": "hr-2026.1", + "liveToday": "hr-2026.2", + "trainedAsKnownThen": true, + "trainedAsKnownNow": false +} diff --git a/docs/snippets/home/site-safety/output/http.json b/docs/snippets/home/site-safety/output/http.json new file mode 100644 index 0000000..5728769 --- /dev/null +++ b/docs/snippets/home/site-safety/output/http.json @@ -0,0 +1,12 @@ +{ + "asKnownThen": { + "id": "worker:maria", + "type": "Worker", + "attributes": { ":worker/name": "Maria", ":worker/trained-for": ["site:harbor"] } + }, + "asKnownNow": { + "id": "worker:maria", + "type": "Worker", + "attributes": { ":worker/name": "Maria" } + } +} diff --git a/docs/snippets/home/site-safety/output/open-work.json b/docs/snippets/home/site-safety/output/open-work.json index 3d01a3f..b7e75fe 100644 --- a/docs/snippets/home/site-safety/output/open-work.json +++ b/docs/snippets/home/site-safety/output/open-work.json @@ -1,13 +1,11 @@ -[ - { - "on": "2026-03-03", +{ + "2026-03-03": { "open": [{ "?worker": "worker:maria", "?site": "site:harbor" }], - "recheckOn": "2026-03-05" + "recheckAt": "2026-03-05T00:00:00.000Z" }, - { "on": "2026-04-01", "open": [], "recheckOn": "2026-06-01" }, - { - "on": "2026-06-01", + "2026-04-01": { "open": [], "recheckAt": "2026-06-01T00:00:00.000Z" }, + "2026-06-01": { "open": [{ "?worker": "worker:maria", "?site": "site:harbor" }], - "recheckOn": null + "recheckAt": null } -] +} diff --git a/docs/snippets/home/site-safety/output/stack.json b/docs/snippets/home/site-safety/output/stack.json new file mode 100644 index 0000000..3243e26 --- /dev/null +++ b/docs/snippets/home/site-safety/output/stack.json @@ -0,0 +1 @@ +{ "model": 22, "release": 7, "command": 24, "ask": 20, "derive": 26, "run": 17, "total": 116 } diff --git a/docs/snippets/home/site-safety/output/timeline.md b/docs/snippets/home/site-safety/output/timeline.md index 61e8ebd..c1c8c86 100644 --- a/docs/snippets/home/site-safety/output/timeline.md +++ b/docs/snippets/home/site-safety/output/timeline.md @@ -1,8 +1,8 @@ -| Position | Actor | Command | Changes (+ assert, − retract; valid time) | -| -------- | ---------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `triplex/config-store` | — | Release `hr-2026.1`; `live` moved to it | -| 2 | `user:hr` | `onboard:maria` | + `:site/name` `"Harbor"` from 2026-01-05