@akterjs/conformance 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,53 @@
-# Temporary Holding Version
+# @akterjs/conformance
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The guarantees of an Akter engine as executable tests. The local engine in `@akterjs/effect` runs it here, and akter-cloud runs it against its production engine. Every guarantee the docs make links to the test here that proves it, by the test's title.
+
+```ts
+import { it } from "@effect/vitest";
+import { conformance } from "@akterjs/conformance";
+
+it.layer(NodeFileSystem.layer)("the local engine on a folder passes engine conformance", conformance(LocalEngine));
+```
+
+An engine under test is an effect that opens fresh storage for one test and returns the engine on it, a `Layer<ActorHost | ActorRegistry>` (the seam `Akter.serve` needs). The suite builds that layer more than once to restart the engine on the same storage, and drives it only through `ActorHost` with the wire's JSON payloads and replies, so it runs against any engine. The local engine is `Akter.local` on a temporary folder (`tests/engine-conformance.suite.test.ts`). An engine that doesn't serve a guarantee yet skips it by name with `conformanceOf({ engine, skip: { migrationsOnOpen: "why, and the issue that tracks it" } })`, keyed as in `guaranteeTitles`. Every other guarantee runs, so a guarantee added later never goes unchecked. A host that keeps its own tables in the actor's database declares their prefix, `conformanceOf({ engine, hostTables: "engine_", skip: {} })`, and provides the same prefix to `HostedRuntime.hostTables`. The migrations guarantee then ignores only the tables under that prefix, and it checks that an app migration creating a table under it is refused. The suite refuses an empty prefix and `akter_`.
+
+Guarantees, one test each, run with the suite's own `Ledger` actor. By default it is the Effect SDK's (`src/ledger/ledger.actor.ts`). `@akterjs/conformance/plain` exports `plainLedgers`, the same Ledger written with the plain SDK and zod, with the same wire contract, and `conformanceOf({ engine, ledgers: plainLedgers, skip: {} })` runs every guarantee on it, so an engine is checked under both SDKs:
+
+- a reply means the command committed: an engine reopened on the same storage sees every replied command
+- a retried command id returns the recorded outcome and runs the handler once
+- a handler failure rolls back every write the command made
+- caller checks run before the handler: a caller the command doesn't allow changes nothing
+- migrations run when an actor opens, before its first call, and a migration added later runs on the next open
+- queries never write: a write inside a query fails and leaves the actor unchanged
+- a handler may read akter_* tables but never write them: the write fails, names the table and changes nothing
+- live queries update only after a commit: a subscriber sees each committed change and nothing from a rolled-back command
+- a message a command sends is delivered after the command commits, at least once, and a rolled-back command sends none
+- a timer fires once at its due time, and not again after the engine restarts
+
+The computer guarantees are a second suite, `computerConformanceOf({ engine, skip })` from `@akterjs/conformance/computers`, with the suite's `Workbench` actor (`src/workbench/`, Effect SDK only), whose `run` command starts a job that makes each computer call in its own activity and records what each answered, so the suite reads the outcomes back with the `runs` query. An engine serves `Workbench/bench-1` with its computers bound to the job runtime's `Actor.computer(key)`: the local engine with `AKTER_LOCAL_COMPUTERS=true` in the test's `ConfigProvider` (`tests/engine-conformance.suite.test.ts`), so it reaches the Workbench's `Akter.jobs` too. They run on the real clock, because computer calls wait on real processes and machines. A `starting` and a `running` computer both read as `up`, because an engine may answer `ensure` before the machine is running.
+
+- a computer step runs once by its key: sent again, even after the engine restarts, it reads back the outcome it recorded
+- a computer keeps its files across pause, resume, stop and an engine restart
+- a held computer stays paused, or stopped if it was stopped: an ensure, a step, and a resume or pause without its hold are refused until its hold resumes it
+- a computer past the store's limit is refused with ComputerLimitError and makes nothing, and one fits again once another is removed
+- a removed computer is gone with its disk: calls to it fail with ComputerNotFoundError, and ensuring it again starts it empty
+
+The fork guarantees are a third suite, `forkConformanceOf({ engine, skip })` from `@akterjs/conformance/fork`, which forks the suite's `acct-1` Ledger into `acct-5`, and its `bench-1` Workbench, with a running and a stopped computer, into `bench-250`, through `ActorHost.fork`. An engine under test serves all four keys, with the Workbench's computers bound both to its jobs and to its fork, and an engine that places an actor by its key puts each fork's key on its parent's shard, because Akter Cloud forks only within a shard (`acct-5` and `bench-250` hash to their parents' shards there). The local engine runs it with `AKTER_LOCAL_COMPUTERS=true` in `tests/engine-conformance.suite.test.ts`.
+
+- a fork copies an actor as committed at its cut and starts quiet: the copy keeps no pending timer, the two change independently, and a retried fork id makes one copy
+- a fork copies each of the actor's computers by its disk at the cut, stopped: the copy holds the files written before the cut, the original's computers go back to where they were, and the two change independently
+
+The docs page `apps/docs/content/reference/guarantees.md` lists each guarantee with a link titled like its test, and `tests/guarantee-titles.pure.test.ts` fails when a listed guarantee has no test with that title or a test is missing from the page. The titles live in `src/guarantee-titles.pure.ts`.
+
+`pnpm test` runs the suite on Node and `pnpm test:bun` runs it on Bun. `vitest.config.ts` names the runtime as `@akterjs/effect`'s does, so every result reads `|node|` or `|bun|`.
+
+## The client contract
+
+`@akterjs/conformance/client` exports `clientConformanceOf({ target, skip })`, the public-contract fixture for the exported clients. It runs each case through both the Effect client (`akterClient` from `@akterjs/client/effect`) and the Promise client (`createClient` from `@akterjs/client`) against a served app holding the suite's `Tally` actor (`@akterjs/conformance/tally` exports its handlers, `TallyLive`, for the server under test). A target is an effect that serves the app for one test and returns its `url` and the headers of four callers: `user`, whom `Tally` allows; `stranger`, an authenticated caller of a kind `Tally` doesn't declare; `unauthenticated`, whose credentials are missing or invalid; and optionally `foreign`, a caller from another organization or app. A target may also give `freshKey`, the effect that names each case's new actor key; by default it is a random `tally-<uuid>`, and a target that serves only some shards, such as akter-cloud's local harness, supplies keys on those. The cases: create and ensure; a command's success and its contract's typed error; queries, state and live updates with increasing versions; a query right after the caller's own command, which reads that command's write; warm; a refused stranger (`CallerNotAllowedError`) and an unauthenticated caller (`UnauthenticatedError`) that change nothing; a foreign caller refused with `CallerNotAllowedError`; a command whose reply the fixture's `fetch` drops after the server answered, retried with its id and applied once; a live subscription whose sockets the fixture closes, which reconnects and resumes without repeating an update; and disposal, which closes every live socket. Register it with `excludeTestServices: true`, because it runs over a real network on the real clock. `tests/client-contract.suite.test.ts` runs it against `akter dev` (`Akter.serve` on `Akter.local`), skipping `foreign`, and against a deployed stage. A target that can't serve this run fails with `ClientTargetUnsetError` (exported beside the fixture), and each case reports as skipped with its reason.
+
+The stage target reads `AKTER_CLIENT_CONTRACT_URL`, the gateway URL of an app that serves `Tally`, and three bearer tokens: `AKTER_CLIENT_CONTRACT_USER_TOKEN` (a developer of the app's organization), `AKTER_CLIENT_CONTRACT_STRANGER_TOKEN` (a caller the stage lets call but `Tally` doesn't declare, such as a call-scoped API key) and `AKTER_CLIENT_CONTRACT_FOREIGN_TOKEN` (a caller from another organization). Its unauthenticated caller sends a bearer that isn't a token. Without the URL every stage case skips. Deploy the app with `akter deploy --entry packages/conformance/src/tally.actor.ts`, which exports it as `app`, then run `pnpm --filter @akterjs/conformance exec vitest run tests/client-contract.suite.test.ts -t "a deployed stage"` with the four variables set.
+
+Status: the guarantees above pass on the local engine with both SDKs' Ledgers, on Node and on Bun, and the computer guarantees pass on akter-cloud's engine over its simulated control plane. The fork guarantees fork into a key on the parent's own shard, and don't cover a fork across shards; the one with computers checks their disks and states, not that a copy runs none of the original's processes, which the engines' own tests check. The computer guarantees don't cover a computer's processes or memory across a pause, egress, credentials, ingress, or a step's timeout and output limit.
+
+- Depends on: `@akterjs/effect` and `@akterjs/client`; peers `effect`, `vitest` and `@effect/vitest`, and optionally `@akterjs/sdk` and `zod` for `@akterjs/conformance/plain`.
+- Must not depend on: any private package.

package/dist/client-contract.suite.d.mts

@@ -0,0 +1,23 @@
+import { ClientTargetUnsetError } from "./client-target.errors.mjs";
+import { Headers } from "./tally-clients.layer.mjs";
+import { Vitest } from "@effect/vitest";
+import { Effect, Scope } from "effect";
+interface ClientCallers {
+  readonly foreign?: Headers;
+  readonly stranger: Headers;
+  readonly unauthenticated: Headers;
+  readonly user: Headers;
+}
+interface ClientTarget {
+  readonly callers: ClientCallers;
+  readonly freshKey?: Effect.Effect<string>;
+  readonly url: string;
+}
+type Target<Failure, Services> = Effect.Effect<ClientTarget, ClientTargetUnsetError | Failure, Scope.Scope | Services>;
+type CaseName = "commands" | "creation" | "disposal" | "foreign" | "forking" | "lostReply" | "readYourWrites" | "reads" | "reconnect" | "refusals" | "warming";
+interface ClientContract<Failure, Services> {
+  readonly skip: Readonly<Partial<Record<CaseName, string>>>;
+  readonly target: Target<Failure, Services>;
+}
+declare const clientConformanceOf: <Failure, Services>({ skip, target }: ClientContract<Failure, Services>) => (test: Vitest.MethodsNonLive<Services>) => void;
+export { type CaseName, type ClientCallers, type ClientTarget, ClientTargetUnsetError, clientConformanceOf };

package/dist/client-contract.suite.mjs

@@ -0,0 +1,279 @@
+import { ClientTargetUnsetError } from "./client-target.errors.mjs";
+import { clients, wired } from "./tally-clients.layer.mjs";
+import { ShortError } from "./tally.contract.mjs";
+import { ActorAlreadyExistsError, CallerNotAllowedError, UnauthenticatedError } from "@akterjs/effect/contract/errors";
+import { expect } from "@effect/vitest";
+import { Array, Effect, Exit, Function, MutableRef, Option, Queue, Record, Schedule, Schema, Scope, Stream } from "effect";
+import { SecureRandom } from "effect/crypto";
+// src/client-contract.suite.ts
+const none = 0;
+const one = 1;
+const two = 2;
+const three = 3;
+const four = 4;
+const five = 5;
+const eight = 8;
+const nine = 9;
+const pollTries = 250;
+const abnormalClose = 4e3;
+const dropped = "dropped by the client contract fixture";
+const resubscribed = "250 millis";
+const updateDeadline = "10 seconds";
+const randomKey = Effect.sync(() => `tally-${SecureRandom.uuidV4Unsafe()}`);
+const freshKeyOf = ({ freshKey }) => Option.getOrElse(Option.fromNullishOr(freshKey), () => randomKey);
+const polled = (read, done) => Effect.filterOrFail(read, done, () => "not yet").pipe(Effect.retry({
+	schedule: Schedule.spaced("20 millis"),
+	times: pollTries
+}), Effect.orDie);
+const nextOf = (queue) => Effect.timeoutOrElse(Queue.take(queue), {
+	duration: updateDeadline,
+	orElse: () => Effect.die(`no live update arrived within ${updateDeadline}`)
+});
+const collected = (updates) => Effect.gen(function* collect() {
+	const queue = yield* Queue.unbounded();
+	yield* Effect.forkScoped(Effect.matchEffect(Stream.runForEach(updates, (update) => Queue.offer(queue, update)), {
+		onFailure: (failure) => Queue.fail(queue, failure),
+		onSuccess: () => Effect.void
+	}));
+	return queue;
+});
+const headOf = (updates) => Effect.flatMap(Stream.runHead(updates), Effect.fromOption);
+const handle = ({ connect, target, wire }, headers, key) => Effect.map(connect({
+	headers,
+	url: target.url,
+	wire
+}), (connected) => connected(key));
+const reasonOf = (effect) => Effect.match(effect, {
+	onFailure: (failure) => failure.reason,
+	onSuccess: (succeeded) => ({ succeeded })
+});
+const created = Effect.fnUntraced(function* created(test) {
+	const key = yield* freshKeyOf(test.target);
+	const tally = yield* handle(test, test.target.callers.user, key);
+	yield* tally.create("ada");
+	return {
+		key,
+		tally
+	};
+});
+const creation = Effect.fnUntraced(function* creation(test) {
+	const { tally } = yield* created(test);
+	const again = yield* reasonOf(tally.create("bob"));
+	yield* tally.ensure("bob");
+	const owner = yield* tally.owner;
+	expect(again).toBeInstanceOf(ActorAlreadyExistsError);
+	expect(owner).toBe("ada");
+});
+const commands = Effect.fnUntraced(function* commands(test) {
+	const { tally } = yield* created(test);
+	const added = yield* tally.add(five);
+	const short = yield* reasonOf(tally.take(nine));
+	const taken = yield* tally.take(two);
+	expect([added, taken]).toStrictEqual([five, three]);
+	expect(short).toBeInstanceOf(ShortError);
+	expect(short).toStrictEqual(ShortError.make({ total: five }));
+});
+const reads = Effect.fnUntraced(function* reads(test) {
+	const { tally } = yield* created(test);
+	yield* tally.add(four);
+	const totals = yield* collected(tally.totals);
+	const [total, first, state] = yield* Effect.all([
+		tally.total,
+		nextOf(totals),
+		headOf(tally.state)
+	]);
+	yield* tally.add(one);
+	const next = yield* nextOf(totals);
+	expect([
+		total,
+		first.value,
+		next.value
+	]).toStrictEqual([
+		four,
+		four,
+		five
+	]);
+	expect(state).toStrictEqual({
+		value: {
+			owner: "ada",
+			total: four
+		},
+		version: first.version
+	});
+	expect(next.version).toBeGreaterThan(first.version);
+});
+const readYourWrites = Effect.fnUntraced(function* readYourWrites(test) {
+	const { tally } = yield* created(test);
+	const seen = yield* Effect.forEach(Array.makeBy(five, Function.identity), () => Effect.andThen(tally.total, Effect.andThen(tally.add(one), tally.total)));
+	expect(seen).toStrictEqual([
+		one,
+		two,
+		three,
+		four,
+		five
+	]);
+});
+const forkTargets = Effect.fnUntraced(function* forkTargets(test) {
+	const [first, second, taken] = yield* Effect.all([
+		freshKeyOf(test.target),
+		freshKeyOf(test.target),
+		freshKeyOf(test.target)
+	]);
+	return {
+		first,
+		occupied: yield* handle(test, test.target.callers.user, taken),
+		second,
+		taken
+	};
+});
+const forking = Effect.fnUntraced(function* forking(test) {
+	const { tally } = yield* created(test);
+	const { first, occupied, second, taken } = yield* forkTargets(test);
+	yield* Effect.andThen(tally.add(three), test.wire.loseNextReply);
+	const child = yield* tally.fork(first);
+	const sibling = yield* Effect.andThen(tally.add(one), tally.fork(second));
+	yield* Effect.andThen(child.add(five), occupied.create("bob"));
+	const totals = Effect.all([
+		tally.total,
+		child.total,
+		sibling.total,
+		child.owner,
+		occupied.owner
+	]);
+	const [refused, read] = yield* Effect.all([reasonOf(tally.fork(taken)), totals]);
+	expect(read).toStrictEqual([
+		four,
+		eight,
+		four,
+		"ada",
+		"bob"
+	]);
+	expect(refused).toBeInstanceOf(ActorAlreadyExistsError);
+});
+const warming = Effect.fnUntraced(function* warming(test) {
+	const { tally } = yield* created(test);
+	const never = yield* Effect.flatMap(freshKeyOf(test.target), (key) => handle(test, test.target.callers.user, key));
+	const before = yield* headOf(tally.state);
+	yield* Effect.all([tally.warm, never.warm]);
+	const after = yield* headOf(tally.state);
+	yield* never.create("bob");
+	const owner = yield* never.owner;
+	expect([after, owner]).toStrictEqual([before, "bob"]);
+});
+const refusals = Effect.fnUntraced(function* refusals(test) {
+	const { key, tally } = yield* created(test);
+	const { stranger, unauthenticated } = test.target.callers;
+	const [robot, anyone] = yield* Effect.all([handle(test, stranger, key), handle(test, unauthenticated, key)]);
+	const refused = yield* reasonOf(robot.add(one));
+	const anonymous = yield* reasonOf(anyone.add(one));
+	const total = yield* tally.total;
+	expect(refused).toBeInstanceOf(CallerNotAllowedError);
+	expect(anonymous).toBeInstanceOf(UnauthenticatedError);
+	expect(total).toBe(none);
+});
+const outsiders = (headers) => Effect.fnUntraced(function* refuseOutsiders(test) {
+	const { key } = yield* created(test);
+	const outsider = yield* handle(test, headers, key);
+	const refused = yield* reasonOf(outsider.add(one));
+	const read = yield* reasonOf(outsider.total);
+	expect(refused).toBeInstanceOf(CallerNotAllowedError);
+	expect(read).toBeInstanceOf(CallerNotAllowedError);
+});
+const lostReply = Effect.fnUntraced(function* lostReply(test) {
+	const { tally } = yield* created(test);
+	yield* test.wire.loseNextReply;
+	const added = yield* tally.add(three);
+	const total = yield* tally.total;
+	expect([added, total]).toStrictEqual([three, three]);
+});
+const dropSockets = ({ wire }) => Effect.gen(function* dropEverySocket() {
+	const before = MutableRef.get(wire.opened);
+	yield* Effect.sync(() => {
+		for (const socket of wire.sockets) socket.close(abnormalClose, dropped);
+	});
+	yield* polled(Effect.sync(() => MutableRef.get(wire.opened)), (count) => count > before);
+	yield* Effect.sleep(resubscribed);
+});
+const reconnect = Effect.fnUntraced(function* reconnect(test) {
+	const { tally } = yield* created(test);
+	const totals = yield* collected(tally.totals);
+	const first = yield* nextOf(totals);
+	const next = yield* Effect.andThen(Effect.andThen(dropSockets(test), tally.add(two)), nextOf(totals));
+	yield* tally.add(one);
+	const last = yield* nextOf(totals);
+	expect([
+		first.value,
+		next.value,
+		last.value
+	]).toStrictEqual([
+		none,
+		two,
+		three
+	]);
+	expect(next.version).toBeGreaterThan(first.version);
+	expect(last.version).toBeGreaterThan(next.version);
+});
+const disposal = Effect.fnUntraced(function* disposal(test) {
+	const scope = yield* Scope.make();
+	const { tally } = yield* Scope.provide(created(test), scope);
+	const totals = yield* Scope.provide(collected(tally.totals), scope);
+	yield* nextOf(totals);
+	const open = test.wire.sockets.size;
+	yield* Scope.close(scope, Exit.void);
+	const left = yield* polled(Effect.sync(() => test.wire.sockets.size), (size) => size === none);
+	expect([open, left]).toStrictEqual([one, none]);
+});
+const titles = {
+	commands: "a command replies with its success or the contract's typed error",
+	creation: "create makes the actor once, and ensure attaches to it",
+	disposal: "disposing the client closes its live sockets",
+	foreign: "a caller from another organization or app is refused with CallerNotAllowedError",
+	forking: "a fork copies the actor at one cut into a new key, independent of its parent and siblings, once per fork id",
+	lostReply: "a command whose reply was lost is retried with its id and runs once",
+	readYourWrites: "a query right after the caller's own command reads that command's write",
+	reads: "queries and state read committed state, and live updates carry increasing versions",
+	reconnect: "a subscription that loses its socket reconnects and resumes without repeating an update",
+	refusals: "a caller the contract doesn't allow, or one without valid credentials, is refused and changes nothing",
+	warming: "warm opens an actor without changing it, and does nothing for a key never created"
+};
+const casesOf = (callers) => ({
+	commands,
+	creation,
+	disposal,
+	foreign: Option.match(Option.fromNullishOr(callers.foreign), {
+		onNone: () => () => Effect.die("this target declares no caller from another organization or app"),
+		onSome: outsiders
+	}),
+	forking,
+	lostReply,
+	readYourWrites,
+	reads,
+	reconnect,
+	refusals,
+	warming
+});
+const perTest = 6e4;
+const isUnset = Schema.is(ClientTargetUnsetError);
+const clientConformanceOf = ({ skip, target }) => (test) => {
+	for (const [client, connect] of clients) for (const name of Record.keys(titles)) {
+		const title = `${client}: ${titles[name]}`;
+		const run = ({ skip: skipCase }) => Effect.scoped(Effect.gen(function* runCase() {
+			const resolved = yield* target;
+			const wire = yield* wired;
+			yield* casesOf(resolved.callers)[name]({
+				connect,
+				target: resolved,
+				wire
+			});
+		})).pipe(Effect.catchIf(isUnset, ({ reason }) => Effect.sync(() => skipCase(reason))));
+		Option.match(Option.fromNullishOr(skip[name]), {
+			onNone: () => {
+				test.effect(title, run, perTest);
+			},
+			onSome: (reason) => {
+				test.effect.skip(`${title} (skipped: ${reason})`, run);
+			}
+		});
+	}
+};
+export { ClientTargetUnsetError, clientConformanceOf };

package/dist/client-target.errors.d.mts

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+declare const ClientTargetUnsetError_base: Schema.Class<ClientTargetUnsetError, Schema.TaggedStruct<"ClientTargetUnsetError", {
+  readonly reason: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+export declare class ClientTargetUnsetError extends ClientTargetUnsetError_base {}
+export {};

package/dist/client-target.errors.mjs

@@ -0,0 +1,4 @@
+import { Schema } from "effect";
+// src/client-target.errors.ts
+var ClientTargetUnsetError = class extends Schema.TaggedError()("ClientTargetUnsetError", { reason: Schema.String }) {};
+export { ClientTargetUnsetError };

package/dist/engine-conformance.suite.d.mts

@@ -0,0 +1,19 @@
+import { guaranteeTitles } from "./guarantee-titles.pure.mjs";
+import { Ledgers } from "./ledger/ledger.actor.mjs";
+import { Vitest } from "@effect/vitest";
+import { Effect, Layer, Scope } from "effect";
+import { ActorHost } from "@akterjs/effect";
+import { ActorRegistry } from "@akterjs/effect/contract/actor-registry";
+type Storage<Failure> = Layer.Layer<ActorHost | ActorRegistry, Failure>;
+type Engine<Failure, Services> = Effect.Effect<Storage<Failure>, Failure, Scope.Scope | Services>;
+type GuaranteeName = keyof typeof guaranteeTitles;
+interface Skipping<Failure, Services> {
+  readonly engine: Engine<Failure, Services>;
+  readonly hostTables?: string;
+  /** The Ledger implementation to run: the Effect SDK's by default, or the plain SDK's from `@akterjs/conformance/plain`. */
+  readonly ledgers?: Ledgers;
+  readonly skip: Readonly<Partial<Record<GuaranteeName, string>>>;
+}
+declare const conformanceOf: <Failure, Services>({ engine, hostTables, ledgers, skip }: Skipping<Failure, Services>) => ((test: Vitest.MethodsNonLive<Services>) => void);
+declare const conformance: <Failure, Services>(engine: Engine<Failure, Services>) => ((test: Vitest.MethodsNonLive<Services>) => void);
+export { type Engine, type GuaranteeName, type Ledgers, type Storage, conformance, conformanceOf };