@akterjs/conformance 0.0.0-stage → 0.1.0

package/dist/ledger/ledger-calls.pure.d.mts

@@ -0,0 +1,79 @@
+import { Ledger, OverdrawnError } from "./ledger.contract.mjs";
+import { Duration, Effect, Exit, Schema } from "effect";
+import { ActorHost } from "@akterjs/effect";
+/** The callers, keys, amounts and payloads the engine conformance suite sends the Ledger, as the JSON the wire carries. */
+interface Sent {
+  readonly account?: string;
+  readonly commandId: string;
+  readonly payload: string;
+  readonly principal?: string;
+}
+declare const ada = "{\"kind\":\"user\",\"principal\":{\"id\":\"ada\"}}";
+declare const billing = "{\"kind\":\"service\",\"principal\":{\"id\":\"billing\"}}";
+declare const bob = "{\"kind\":\"user\",\"principal\":{\"id\":\"bob\"}}";
+/** The one user the Ledger's file rule lets write. */
+declare const fileWriter = "ada";
+/** `akter.files` payloads: a read, an upload, and an upload whose payload claims to be ada's. */
+declare const reading = "{\"access\":\"read\",\"path\":\"statements/may.pdf\"}";
+declare const writing = "{\"access\":\"write\",\"path\":\"\"}";
+/** What the rule decides for bob's read, write and forged write, ada's write, billing's read, then ada's write once closed. */
+declare const fileDecisions: string[];
+declare const forgedWriting = "{\"access\":\"write\",\"path\":\"\",\"principal\":{\"kind\":\"user\",\"principal\":{\"id\":\"ada\"}}}";
+declare const key = "acct-1";
+declare const payee = "acct-2";
+/**
+ * The key a fork of `acct-1` goes into. Akter Cloud forks only into a key on the parent's own shard, and `acct-5` hashes
+ * to `acct-1`'s shard, so an engine that serves one serves the other.
+ */
+declare const forked = "acct-5";
+declare const nothing = "null";
+declare const opening = 5;
+declare const topUp = 7;
+/** `topUp` as the patched build releases it for a hold it started: twice over. */
+declare const topUpDoubled = 14;
+declare const overdraft = 9;
+declare const lostInCrash = 3;
+declare const refill = 1;
+declare const transferred = 2;
+declare const beforeDue: Duration.Input;
+declare const untilDue: Duration.Input;
+declare const longAfterDue: Duration.Input;
+declare const amountLater: (value: number) => string;
+declare const amountTo: (value: number) => string;
+declare const amount: (value: number) => string;
+declare const overdrawnBy: OverdrawnError;
+declare const depositOpening: Sent;
+declare const withdrawOverdraft: Sent;
+declare const robotDeposit: Sent;
+interface Approving {
+  readonly amount: number;
+  readonly job: string;
+  readonly refuse: boolean;
+}
+declare const approving: ({ amount: value, job, refuse }: Approving) => string;
+/** How the engine conformance suite calls the Ledger on an engine: commands and queries as JSON, replies decoded. */
+type Host = ActorHost["Service"];
+type Reply = ReturnType<Host["command"]>;
+type Unexpected = Effect.Error<Reply> | Effect.Error<ReturnType<Host["fork"]>> | Schema.SchemaError;
+declare const send: (host: Host, member: string, { account, commandId, payload, principal }: Sent) => Reply;
+declare const ask: (host: Host, member: string, holder?: string) => Reply;
+declare const account: (host: Host, holder?: string) => Effect.Effect<Exit.Exit<typeof Ledger.queries.account.success.Type>, Unexpected>;
+/** Forks `acct-1` into `into`, which is `forked` by default, and answers the parent's version at the cut. */
+declare const fork: (host: Host, commandId: string, into?: string) => ReturnType<Host["fork"]>;
+declare const amounts: (host: Host, holder?: string) => Effect.Effect<Exit.Exit<readonly number[]>, Unexpected>;
+declare const approve: (host: Host, commandId: string, payload: string) => Reply;
+declare const drained: (host: Host) => ReturnType<typeof amounts>;
+/** Holds funds: starts a `release` job and returns its id. */
+declare const held: (host: Host, commandId: string) => Effect.Effect<string, Unexpected>;
+/** The calls, as one namespace: `send`, `ask`, `approve` and `held` take the host first. */
+declare const ledgerHost: {
+  account: typeof account;
+  amounts: typeof amounts;
+  approve: typeof approve;
+  ask: typeof ask;
+  drained: typeof drained;
+  fork: typeof fork;
+  held: typeof held;
+  send: typeof send;
+};
+export { type Host, type Reply, type Sent, type Unexpected, ada, amount, amountLater, amountTo, approving, beforeDue, billing, bob, depositOpening, fileDecisions, fileWriter, forgedWriting, forked, key, ledgerHost, longAfterDue, lostInCrash, nothing, opening, overdraft, overdrawnBy, payee, reading, refill, robotDeposit, topUp, topUpDoubled, transferred, untilDue, withdrawOverdraft, writing };

package/dist/ledger/ledger-calls.pure.mjs

@@ -0,0 +1,111 @@
+import { decodeReply } from "./ledger-checks.pure.mjs";
+import { Cents, Ledger, OverdrawnError } from "./ledger.contract.mjs";
+import { Array, Effect, Exit } from "effect";
+// src/ledger/ledger-calls.pure.ts
+const ada = "{\"kind\":\"user\",\"principal\":{\"id\":\"ada\"}}";
+const billing = "{\"kind\":\"service\",\"principal\":{\"id\":\"billing\"}}";
+const bob = "{\"kind\":\"user\",\"principal\":{\"id\":\"bob\"}}";
+/** The one user the Ledger's file rule lets write. */
+const fileWriter = "ada";
+/** `akter.files` payloads: a read, an upload, and an upload whose payload claims to be ada's. */
+const reading = "{\"access\":\"read\",\"path\":\"statements/may.pdf\"}";
+const writing = "{\"access\":\"write\",\"path\":\"\"}";
+/** What the rule decides for bob's read, write and forged write, ada's write, billing's read, then ada's write once closed. */
+const fileDecisions = [
+	"allowed",
+	"denied",
+	"denied",
+	"allowed",
+	"CallerNotAllowedError",
+	"denied"
+];
+const forgedWriting = "{\"access\":\"write\",\"path\":\"\",\"principal\":{\"kind\":\"user\",\"principal\":{\"id\":\"ada\"}}}";
+const robot = "{\"kind\":\"robot\",\"principal\":{\"id\":\"r2\"}}";
+const key = "acct-1";
+const payee = "acct-2";
+/**
+* The key a fork of `acct-1` goes into. Akter Cloud forks only into a key on the parent's own shard, and `acct-5` hashes
+* to `acct-1`'s shard, so an engine that serves one serves the other.
+*/
+const forked = "acct-5";
+const nothing = "null";
+const opening = 5;
+const topUp = 7;
+/** `topUp` as the patched build releases it for a hold it started: twice over. */
+const topUpDoubled = 14;
+const overdraft = 9;
+const lostInCrash = 3;
+const refill = 1;
+const transferred = 2;
+const dueMinutes = 5;
+const beforeDue = "4 minutes";
+const untilDue = "1 minute";
+const longAfterDue = "10 minutes";
+const amountLater = (value) => `{"amount":${value},"minutes":${dueMinutes}}`;
+const amountTo = (value) => `{"amount":${value},"to":"${payee}"}`;
+const amount = (value) => `{"amount":${value}}`;
+const overdrawnBy = OverdrawnError.make({ balance: Cents.make(-4) });
+const depositOpening = {
+	commandId: "a",
+	payload: amount(5)
+};
+const withdrawOverdraft = {
+	commandId: "w",
+	payload: amount(9)
+};
+const robotDeposit = {
+	commandId: "d-robot",
+	payload: amount(5),
+	principal: robot
+};
+const approving = ({ amount: value, job, refuse }) => `{"amount":${value},"job":"${job}","refuse":${refuse}}`;
+const send = (host, member, { account = key, commandId, payload, principal = ada }) => host.command({
+	actor: "Ledger",
+	commandId,
+	key: account,
+	member,
+	payload,
+	principal
+});
+const ask = (host, member, holder = key) => host.query({
+	actor: "Ledger",
+	key: holder,
+	member,
+	payload: nothing,
+	principal: ada
+});
+const account = (host, holder = key) => Effect.flatMap(ask(host, "account", holder), (reply) => decodeReply(Ledger.queries.account, reply));
+/** Forks `acct-1` into `into`, which is `forked` by default, and answers the parent's version at the cut. */
+const fork = (host, commandId, into = forked) => host.fork({
+	actor: "Ledger",
+	commandId,
+	into,
+	key
+});
+const amounts = (host, holder = key) => Effect.map(Effect.flatMap(ask(host, "entries", holder), (reply) => decodeReply(Ledger.queries.entries, reply)), Exit.map(Array.map((entry) => entry.amount)));
+const approve = (host, commandId, payload) => send(host, "approve", {
+	commandId,
+	payload
+});
+const drained = (host) => Effect.gen(function* drainThenRead() {
+	yield* account(host);
+	yield* host.drain;
+	return yield* amounts(host);
+});
+/** Holds funds: starts a `release` job and returns its id. */
+const held = (host, commandId) => Effect.flatMap(send(host, "hold", {
+	commandId,
+	payload: nothing
+}), (reply) => Effect.flatten(decodeReply(Ledger.commands.hold, reply)));
+/** The calls, as one namespace: `send`, `ask`, `approve` and `held` take the host first. */
+const ledgerHost = {
+	account,
+	amounts,
+	approve,
+	ask,
+	drained,
+	fork,
+	held,
+	send
+};
+export { ada, amount, amountLater, amountTo, approving, beforeDue, billing, bob, depositOpening, fileDecisions, fileWriter, forgedWriting, forked, key, ledgerHost, longAfterDue, lostInCrash, nothing, opening, overdraft, overdrawnBy, payee, reading, refill, robotDeposit, topUp, topUpDoubled, transferred, untilDue, withdrawOverdraft, writing };

package/dist/ledger/ledger-checks.pure.d.mts

@@ -0,0 +1,21 @@
+import { Effect, Exit, Option, Schema } from "effect";
+/** Checks the engine conformance suite applies to replies, table names and an engine's declared host table prefix. */
+declare const akterTables = "akter_";
+declare const isHostTable: ({ hostTables }: {
+  readonly hostTables: Option.Option<string>;
+}) => (name: string) => boolean;
+declare const isRefused: <Failure>(reply: Effect.Effect<string, Failure>) => Effect.Effect<boolean>;
+interface Declaration<Success, SuccessEncoded, Failure, FailureEncoded> {
+  readonly error: Schema.Codec<Failure, FailureEncoded>;
+  readonly success: Schema.Codec<Success, SuccessEncoded>;
+}
+type Decoded<Success, Failure> = Effect.Effect<Exit.Exit<Success, Failure>, Schema.SchemaError>;
+/** Decodes a member's reply, as the engine encodes it, to its exit. */
+declare const decodeReply: {
+  (reply: string): <Success, SuccessEncoded, Failure, FailureEncoded>(declaration: Declaration<Success, SuccessEncoded, Failure, FailureEncoded>) => Decoded<Success, Failure>;
+  <Success, SuccessEncoded, Failure, FailureEncoded>(declaration: Declaration<Success, SuccessEncoded, Failure, FailureEncoded>, reply: string): Decoded<Success, Failure>;
+};
+/** What an actor's file rule decided for one `akter.files` query: `allowed`, `denied`, or the caller's refusal. */
+declare const fileDecision: <Failure>(reply: Effect.Effect<string, Failure>) => Effect.Effect<string, Schema.SchemaError>;
+declare const refusedPrefix: (prefix: string) => Option.Option<string>;
+export { akterTables, decodeReply, fileDecision, isHostTable, isRefused, refusedPrefix };

package/dist/ledger/ledger-checks.pure.mjs

@@ -0,0 +1,37 @@
+import { FileAccessDeniedError } from "@akterjs/effect/contract/errors";
+import { Effect, Exit, Option, Predicate, Schema, String } from "effect";
+import { dual } from "effect/Function";
+// src/ledger/ledger-checks.pure.ts
+/** Checks the engine conformance suite applies to replies, table names and an engine's declared host table prefix. */
+const akterTables = "akter_";
+const isHostTable = ({ hostTables }) => (name) => {
+	const lowered = String.toLowerCase(name);
+	const prefix = Option.map(hostTables, String.toLowerCase);
+	return Option.exists(prefix, (lower) => String.startsWith(lower)(lowered));
+};
+const isRefused = (reply) => Effect.match(reply, {
+	onFailure: (failure) => Predicate.isTagged(failure, "CallerNotAllowedError"),
+	onSuccess: () => false
+});
+/** Decodes a member's reply, as the engine encodes it, to its exit. */
+const decodeReply = dual(2, (declaration, reply) => {
+	const exit = Schema.Exit(declaration.success, declaration.error, Schema.Defect());
+	return Schema.decodeEffect(Schema.fromJsonString(Schema.toCodecJson(exit)))(reply);
+});
+/** What an actor's file rule decided for one `akter.files` query: `allowed`, `denied`, or the caller's refusal. */
+const fileDecision = (reply) => Effect.matchEffect(reply, {
+	onFailure: (failure) => Option.liftPredicate(failure, Predicate.isTagged("CallerNotAllowedError")).pipe(Option.as("CallerNotAllowedError"), Option.getOrElse(() => "failed"), Effect.succeed),
+	onSuccess: (text) => Effect.map(decodeReply({
+		error: FileAccessDeniedError,
+		success: Schema.Void
+	}, text), Exit.match({
+		onFailure: () => "denied",
+		onSuccess: () => "allowed"
+	}))
+});
+const refusedPrefix = (prefix) => {
+	if (String.isEmpty(prefix)) return Option.some("an empty prefix would match every table");
+	if (String.toLowerCase(prefix) === "akter_") return Option.some(`${akterTables} is Akter's own prefix`);
+	return Option.none();
+};
+export { akterTables, decodeReply, fileDecision, isHostTable, isRefused, refusedPrefix };

package/dist/ledger/ledger.actor.d.mts

@@ -0,0 +1,13 @@
+import { Layer } from "effect";
+/** A Ledger implementation the suite serves on the engine, from either SDK. */
+type LedgerLayer = Layer.Layer<never>;
+/** The Ledger at each migration step the suite opens: entries only, entries and notes, and one that creates a table under the engine's prefix. */
+interface Ledgers {
+  readonly intruding: (prefix: string) => LedgerLayer;
+  readonly live: LedgerLayer;
+  /** `live` deployed again with its `release` job patched (`doubled`), over holds the earlier build started. */
+  readonly patched: LedgerLayer;
+  readonly withNotes: LedgerLayer;
+}
+declare const effectLedgers: Ledgers;
+export { type LedgerLayer, type Ledgers, effectLedgers };

package/dist/ledger/ledger.actor.mjs

@@ -0,0 +1,115 @@
+import "./ledger-calls.pure.mjs";
+import { Cents, EntryId, Ledger, OverdrawnError, PatchedLedger } from "./ledger.contract.mjs";
+import { FileAccessDeniedError } from "@akterjs/effect/contract/errors";
+import { Array, Duration, Effect, Exit, Layer } from "effect";
+import { Akter } from "@akterjs/effect/contract";
+import { Akter as Akter$1 } from "@akterjs/effect";
+import { DurableDeferred } from "effect/workflow";
+// src/ledger/ledger.actor.ts
+const lowestBalance = 0;
+const entriesVersion = 1;
+const notesVersion = 2;
+const reservedVersion = 3;
+const record = Effect.fnUntraced(function* record(balance, amount) {
+	const minted = yield* Akter.id;
+	const id = EntryId.make(minted);
+	const sql = yield* Akter.sql;
+	yield* sql`INSERT INTO entries ${sql.insert({
+		amount,
+		id
+	})}`;
+	yield* Ledger.update({ balance });
+	return id;
+});
+const withdrawal = Effect.fnUntraced(function* withdrawal(ledger, amount) {
+	const balance = Cents.make(ledger.balance - amount);
+	const id = yield* record(balance, amount);
+	if (balance < lowestBalance) return yield* OverdrawnError.make({ balance });
+	return id;
+});
+/** Writes an entry, reads the engine's journal, then writes the engine's state table, which no handler may do. */
+const tamper = Effect.fnUntraced(function* tamper(balance, amount) {
+	yield* record(balance, amount);
+	const sql = yield* Akter.sql;
+	yield* sql`SELECT count(*) AS commands FROM akter_commands`;
+	yield* sql`UPDATE akter_state SET value = value`;
+});
+/** The amount a person approves for release: `hold` starts a job that waits for it, and `approve` signals it. */
+const approval = DurableDeferred.make("approval", { success: Cents });
+/** Signals the held job, then fails after the signal when `refuse` is set, so the command rolls back with it. */
+const refusal = Effect.die(/* @__PURE__ */ new Error("the approval was refused after signalling"));
+const approve = (amount, job, refuse) => {
+	const signalled = Akter.signal(approval, {
+		job,
+		value: amount
+	});
+	if (refuse) return Effect.andThen(signalled, refusal);
+	return signalled;
+};
+/** Any user reads the ledger's files; only ada writes them, and no one once the account is closed. */
+const fileRule = (ledger, { access, path }) => Ledger.principal.pipe(Effect.filterOrFail((caller) => access === "read" || caller.id === "ada" && !ledger.closed, () => FileAccessDeniedError.make({
+	access,
+	message: "only ada writes, while the account is open",
+	path
+})), Effect.asVoid);
+const ledgerLayer = (migrations, holding = Ledger.jobs.release) => Ledger.toLayer({
+	commands: {
+		approve: (_ledger, { amount, job, refuse }) => approve(amount, job, refuse),
+		close: () => Ledger.update({ closed: true }),
+		crash: (ledger, { amount }) => Effect.andThen(record(Cents.make(ledger.balance + amount), amount), Effect.die(/* @__PURE__ */ new Error("the handler crashed after writing"))),
+		credit: (ledger, { amount }) => record(Cents.make(ledger.balance + amount), amount),
+		deposit: (ledger, { amount }) => record(Cents.make(ledger.balance + amount), amount),
+		depositLater: (_ledger, { amount, minutes }) => Effect.asVoid(Akter.schedule(Duration.minutes(minutes), Ledger.commands.deposit, { amount })),
+		hold: () => Akter.start(holding, {}),
+		tamper: (ledger, { amount }) => tamper(Cents.make(ledger.balance + amount), amount),
+		transfer: (ledger, { amount, to }) => Effect.andThen(Akter.send(Ledger.commands.credit, to, { amount }), withdrawal(ledger, amount)),
+		withdraw: (ledger, { amount }) => withdrawal(ledger, amount)
+	},
+	files: { authorize: fileRule },
+	migrations,
+	queries: {
+		account: (ledger) => Effect.succeed({
+			balance: ledger.balance,
+			closed: ledger.closed
+		}),
+		entries: () => Effect.flatMap(Akter.sql, (sql) => sql`SELECT id, amount FROM entries ORDER BY rowid`),
+		scribble: () => Effect.asVoid(Effect.flatMap(Akter.sql, (sql) => sql`INSERT INTO entries ${sql.insert({
+			amount: 1,
+			id: "query"
+		})}`)),
+		tables: () => Effect.flatMap(Akter.sql, (sql) => Effect.map(sql`SELECT name FROM sqlite_schema WHERE type = 'table' AND name NOT LIKE 'akter_%' AND name NOT LIKE 'sqlite_%' ORDER BY name`, Array.map((row) => row.name)))
+	},
+	results: { release: (ledger, result) => Exit.match(result, {
+		onFailure: () => Effect.void,
+		onSuccess: (amount) => Effect.asVoid(record(Cents.make(ledger.balance + amount), amount))
+	}) }
+});
+const releaseLive = Ledger.jobs.release.toLayer(() => DurableDeferred.await(approval));
+const twice = 2;
+/** The later build's release: twice the approved amount, but only for a hold this build started. */
+const doublingReleaseLive = PatchedLedger.jobs.release.toLayer(() => Effect.gen(function* doublingRelease() {
+	const amount = yield* DurableDeferred.await(approval);
+	if (yield* PatchedLedger.jobs.release.patched("double")) return Cents.make(amount * twice);
+	return amount;
+}));
+/** Serves the Ledger with its job on the engine's job runtime, as an app does. */
+const withJobs = (ledger, release = releaseLive) => Layer.merge(ledger, release).pipe(Layer.provide(Akter$1.jobs));
+const createEntries = (sql) => sql`CREATE TABLE entries (id TEXT PRIMARY KEY, amount INTEGER NOT NULL)`;
+const createNotes = (sql) => sql`CREATE TABLE notes (id TEXT PRIMARY KEY, text TEXT NOT NULL)`;
+const LedgerLive = withJobs(ledgerLayer({ [entriesVersion]: createEntries }));
+const LedgerWithNotesLive = withJobs(ledgerLayer({
+	[entriesVersion]: createEntries,
+	[notesVersion]: createNotes
+}));
+const ledgerIntruding = (prefix) => withJobs(ledgerLayer({
+	[entriesVersion]: createEntries,
+	[notesVersion]: createNotes,
+	[reservedVersion]: (sql) => sql`CREATE TABLE ${sql(`${prefix}intruder`)} (id TEXT PRIMARY KEY)`
+}));
+const effectLedgers = {
+	intruding: ledgerIntruding,
+	live: LedgerLive,
+	patched: withJobs(ledgerLayer({ [entriesVersion]: createEntries }, PatchedLedger.jobs.release), doublingReleaseLive),
+	withNotes: LedgerWithNotesLive
+};
+export { effectLedgers };