@classytic/arc 2.20.0 → 2.22.0

package/skills/arc-module-publishing/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: arc-module-publishing
+description: |
+  Author and publish an ecosystem package for @classytic/arc the way arc's own packages
+  are built — modules, action presets, and plugins that hosts install and compose.
+  Codifies the non-negotiable conventions: no hardcoded dependencies (host duty), peers
+  as `>=` ranges (stable API contract), bundle-nothing tsdown, public-subpath imports only,
+  one-way dependency (arc never depends on you), and the classytic release gate.
+  Use when creating a new @classytic/arc-<domain> package, extracting a domain out of an
+  app into a reusable module, deciding a package's package.json / tsdown / peer setup,
+  writing a defineModule() or an action preset, or preparing an arc module for npm publish.
+  Triggers: publish arc module, arc package, arc ecosystem, defineModule, ArcModule, arc
+  plugin package, arc action preset, extract domain to package, arc-approval, arc-involvement,
+  peer dependencies arc, tsdown arc package, arc module conventions, classytic publish,
+  mergeResourceConfig, ResourceSeams, kernel-typed engine port, module errorMappers.
+license: MIT
+metadata:
+  author: Classytic
+tags:
+  - arc
+  - packaging
+  - publishing
+  - modules
+  - ecosystem
+  - tsdown
+  - peer-dependencies
+  - monorepo
+---
+
+# Publishing @classytic/arc ecosystem packages
+
+How to author and ship a reusable package **on top of** arc — a domain module, an action
+preset, or a plugin — so it composes cleanly into any host and follows the same discipline
+as arc's own first-party packages (`@classytic/arc-approval`, `@classytic/arc-involvement`,
+`@classytic/arc-notifications`).
+
+**Node ≥22 · ESM only · TypeScript strict · tsdown build · Biome lint.**
+
+---
+
+## The one rule everything else follows
+
+> **The package declares a contract; the host owns the installation.**
+
+A published arc package is a *contribution* to someone else's app, not an app. That single
+idea produces every convention below: you never bundle what the host provides, you never
+pin what the host must choose, you never reach past arc's public surface, and you never
+make arc depend on you.
+
+---
+
+## Decision: which shape are you shipping?
+
+Three shapes, smallest surface first. Pick the smallest that does the job.
+
+| Shape | You export | Host uses it via | Example |
+|---|---|---|---|
+| **Action preset** | a function returning an `actions:` slice | spread into `defineResource({ actions })` | `withApprovalChain()` (arc-approval) |
+| **Plugin** | an `fp()`-wrapped Fastify plugin (+ named export) | `app.register()` / `plugins:` slot | any cross-cutting decorator/hook |
+| **Module** | `createXModule(deps) → ArcModule` | `createApp({ modules: [...] })` | a whole domain (engine + resources + wiring) |
+
+- A preset adds **verbs to one resource**. No lifecycle, no engine — just a function that
+  returns `Record<string, ActionDefinition>`. Storage-agnostic via a **structural repository
+  port** (an interface with the two or three methods you actually call), never a kit import.
+- A module owns a **whole domain**: it initializes an engine in `bootstrap`, registers its
+  resources, wires `afterResources`, and tears down in `onClose`. Use `defineModule` and let
+  the host list it in `modules:`. See [references/authoring-modules.md](references/authoring-modules.md).
+
+When unsure, ship a **preset or plugin**. A module is the right call only when there is
+engine state to boot and multiple resources to register as a unit.
+
+---
+
+## Dependency discipline (the part reviewers keep catching)
+
+This is where packages go wrong. Get the `package.json` dependency fields exactly right:
+
+- **`dependencies`: usually empty.** Everything arc-shaped is a *peer*. Only add a real
+  `dependency` for a genuinely private, bundled-in helper the host should never see or
+  control — which is rare. If you're tempted to add `@classytic/*` or `fastify` here, stop:
+  that's a peer.
+- **`peerDependencies`: `>=` ranges, never `^`.** A peer is a *contract*: "I work against
+  arc 2.20 and up." `^2.20.0` would wrongly forbid a host on arc 3.x that still satisfies the
+  API you use. Use `">=2.20.0"`. This keeps the API contract stable and lets hosts upgrade arc
+  without your package blocking them.
+- **`devDependencies`: pin with `^`.** These are the versions your *test suite* runs against —
+  a concrete, current version (`"@classytic/arc": "^2.20.0"`). The floor of every devDep must
+  be `>=` the peer floor, or your tests never exercise the version you claim to support.
+- **Optional peers** (zod, ioredis, a kit) go in `peerDependencies` **and**
+  `peerDependenciesMeta: { "<name>": { optional: true } }`. Never let their types leak into
+  your public `.d.mts` — use structural typing so a host that doesn't install them still
+  compiles. See [references/package-manifest.md](references/package-manifest.md).
+
+**Why `>=` and not `^` for peers:** the host, not you, resolves the actual installed version.
+Your job is to state the *floor* of the API you depend on and stay out of the host's upgrade
+path. A caret peer turns every host major-bump into a forced wait on your release.
+
+---
+
+## Import discipline: public surface only
+
+Import arc through its **published subpaths**, exactly as a third-party host would. Never
+reach into `@classytic/arc/src/...` or a deep `dist/` path.
+
+```ts
+import type { PermissionCheck } from "@classytic/arc/permissions";
+import { getOrgId, getUserId, requireOrgId } from "@classytic/arc/scope";
+import type { ActionDefinition, RequestWithExtras } from "@classytic/arc/types";
+import { createDomainError, NotFoundError, ValidationError } from "@classytic/arc/utils";
+```
+
+The canonical entry points: `@classytic/arc` (core), `/permissions`, `/scope`, `/types`,
+`/utils`, `/factory` (for `defineModule`, `getModuleExports`), `/testing`. If something you
+need isn't on a public subpath, that's a signal — file it against arc rather than deep-import
+around it. Deep imports break the moment arc reorganizes internals, which it's free to do
+because they were never public.
+
+**One-way dependency:** your package depends on arc; **arc never depends on your package.**
+If arc would need something from you, the abstraction belongs *in arc* (a port, a hook, a
+preset seam), not as a back-edge. This keeps the dependency graph a DAG and arc publishable
+on its own.
+
+---
+
+## Build: bundle nothing
+
+tsdown, ESM only, and **bundle nothing that's a peer**. Every `@classytic/*` and `fastify`
+stays external so the host's single installed copy is the one that runs (two copies of arc =
+two plugin registries = subtle breakage).
+
+```ts
+// tsdown.config.ts
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  format: ["esm"],
+  dts: true,
+  sourcemap: false,
+  clean: true,
+  treeshake: true,
+  target: "node22",
+  outDir: "dist",
+  deps: {
+    skipNodeModulesBundle: true,     // don't inline node_modules
+    neverBundle: [/^@classytic\//],  // arc + primitives + kits stay external, always
+  },
+});
+```
+
+`package.json` build wiring: `sideEffects: false`, `files: ["dist"]`, an `exports` map with
+`types` + `default`, `type: "module"`, `engines.node: ">=22"`, `publishConfig.access:
+"public"`. Full template in [references/package-manifest.md](references/package-manifest.md).
+
+---
+
+## Bridge onto arc's primitives — don't reinvent them
+
+A hard-won lesson: when a host already gets a capability from arc, **bridge onto it** instead
+of shipping a second path.
+
+- Need background work? Use `fastify.jobs` (arc's BullMQ bridge) — don't add your own BullMQ
+  dependency and stand up a parallel queue. Two job systems in one app is a footgun, not a
+  feature.
+- Need guaranteed event delivery? Use arc's **outbox** and the `@classytic/primitives` event
+  contract (`createEvent`, `DomainEvent`, `EventTransport`) — don't invent an event shape.
+- Need permissions/scope? Use `@classytic/arc/permissions` + `@classytic/arc/scope`
+  accessors (`getOrgId`, `requireUserId`) — don't re-derive tenant/user from `request.user`.
+
+The test: *"Does arc already bless a primitive for this?"* If yes, your package composes onto
+it. Shipping a competing path breaks the host's single-source-of-truth and doubles their ops
+surface. Reinvent only when arc genuinely has no primitive — and then consider whether it
+should live in arc.
+
+---
+
+## Naming & versioning
+
+- **Package name:** `@classytic/arc-<domain>` for first-party; third parties use their own
+  scope (`@acme/arc-billing`). The `arc-` prefix signals "arc ecosystem package."
+- **Module `name`** (the `defineModule({ name })` identifier): namespace it so it can't
+  collide in a host that composes many modules — `"accounting"`, `"order"`, or a
+  vendor-qualified `"acme.billing"`. This is the key hosts use in `dependsOn` and
+  `getModuleExports`, and arc rejects duplicate module names at boot.
+- **SemVer the public export**, not the internals. Your exported function signatures, the
+  `ArcModule` shape you return, and the action/schema surface are the contract. Bumping a peer
+  floor (e.g. requiring a newer arc) is at least a **minor**; changing an exported signature is
+  a **major**.
+
+---
+
+## Release gate
+
+Every publish runs a gate — no `--no-verify`, ever. In a workspace, a shared script; in a
+solo package, `prepublishOnly`:
+
+```jsonc
+"scripts": {
+  "build": "tsdown",
+  "typecheck": "tsc --noEmit",
+  "lint": "biome check src/",
+  "prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"
+}
+```
+
+For a **monorepo of packages**, add a **peer-skew gate** that fails if any package's devDep
+floor is below its declared peer floor — it's the mechanical guard that stops your suite from
+silently testing against a version older than you promise to support. Full script and workspace
+layout in [references/publishing-workflow.md](references/publishing-workflow.md).
+
+**classytic packages** additionally: commit as `classytic-bot[bot]` (per-invocation git env
+vars, never `git config --global`, no `Co-Authored-By`), push via `classytic-push`, publish to
+public npm. See the workspace `CLAUDE.md` and [references/publishing-workflow.md](references/publishing-workflow.md).
+
+---
+
+## Pre-publish checklist
+
+- [ ] `dependencies` is empty (or only truly-private bundled helpers)
+- [ ] every arc/fastify/kit dep is a `peerDependency` with a `>=` range
+- [ ] every peer floor is covered by a `^`-pinned devDep at or above it (peer-skew clean)
+- [ ] optional peers are marked `optional: true` and their types don't leak into `dist/*.d.mts`
+- [ ] tsdown `neverBundle: [/^@classytic\//]` + `skipNodeModulesBundle: true`
+- [ ] imports use public subpaths only — no `@classytic/arc/src` or deep `dist` paths
+- [ ] arc has **no** dependency on this package (grep arc for the package name → nothing)
+- [ ] `sideEffects: false`, `files: ["dist"]`, `exports` map with `types`+`default`, `type: "module"`
+- [ ] action schemas shipped as **JSON Schema** (zod stays an optional peer, never required)
+- [ ] `prepublishOnly` gate green (typecheck + lint + test + build), no `--no-verify`
+- [ ] module `name` is namespaced and can't collide across a multi-module host
+- [ ] boots green in a **kit-backed testkit** (real in-memory store, prod-fidelity — not a fake repo)
+- [ ] `.npmrc`: `auto-install-peers=false` + an install-script allowlist for any dep with a `postinstall`
+
+---
+
+## References
+
+- [references/package-manifest.md](references/package-manifest.md) — copy-paste `package.json`
+  + `tsdown.config.ts`, optional-peer structural-typing pattern, the dependency-field cheat sheet.
+- [references/authoring-modules.md](references/authoring-modules.md) — `defineModule` lifecycle,
+  `dependsOn` composition order, `getModuleExports` cross-module wiring, thunk lazy/region packs,
+  action-preset and structural-port patterns.
+- [references/publishing-workflow.md](references/publishing-workflow.md) — monorepo layout, the
+  peer-skew + prepublish gates, classytic bot-identity release steps, versioning a public export.

package/skills/arc-module-publishing/references/authoring-modules.md

@@ -0,0 +1,327 @@
+# Authoring: presets, plugins, and modules
+
+The three shapes a package exports, smallest surface first. All import arc through public
+subpaths only (`@classytic/arc/{permissions,scope,types,utils,factory,testing}`).
+
+---
+
+## Shape 1 — Action preset (add verbs to one resource)
+
+The smallest reusable unit: a function returning an `actions:` slice the host spreads into a
+resource. No lifecycle, no engine. Storage-agnostic via a **structural repository port** — an
+interface listing only the methods you call, satisfied by any kit repository without importing
+the kit.
+
+```ts
+import type { PermissionCheck } from "@classytic/arc/permissions";
+import { getOrgId, getUserId } from "@classytic/arc/scope";
+import type { ActionDefinition, RequestWithExtras } from "@classytic/arc/types";
+import { createDomainError, NotFoundError } from "@classytic/arc/utils";
+
+// Structural port — NOT a kit import. Any kit repo with these methods satisfies it.
+export interface SubjectRepository<TDoc> {
+  getById(id: string, o: { organizationId?: string; throwOnNotFound: false; lean: true }): Promise<TDoc | null>;
+  update(id: string, patch: Record<string, unknown>, o: { organizationId?: string; lean: true }): Promise<TDoc | null>;
+}
+
+export interface WithXConfig<TDoc> {
+  readonly repository: SubjectRepository<TDoc>;
+  readonly permissions: { readonly act: PermissionCheck };
+  // ...host policy injected here: resolvers, side-effect hooks, tenancy mode
+}
+
+export function withX<TDoc>(config: WithXConfig<TDoc>): Record<"do_x", ActionDefinition> {
+  return {
+    do_x: {
+      handler: async (id, data, req) => handler(config, id, data, req),
+      permissions: config.permissions.act,
+      description: "…",
+      schema: { type: "object", /* JSON Schema */ additionalProperties: false },
+    },
+  };
+}
+```
+
+Host composes it:
+
+```ts
+defineResource({
+  actions: {
+    ...withX({ repository, permissions, /* host policy */ }),
+    post: { /* subject-specific verbs stay here */ },
+  },
+});
+```
+
+**Rules that make a preset reusable:**
+- Inject **all policy** through config (permissions, resolvers, side-effect hooks). The preset
+  contributes *mechanism*; the host owns *policy*.
+- Take a **structural port**, never a concrete kit type. `SubjectRepository<TDoc>` with the two
+  methods you use — not `MongooseRepository`.
+- Read tenant/user via `getOrgId(req.scope)` / `getUserId(req.scope)`, never off `req.user`
+  directly. Honor a `tenancy: "required" | "off"` config so single-tenant hosts work too.
+- Ship schemas as **JSON Schema**. Map any domain errors to arc's `createDomainError(code, msg,
+  status)` so the wire contract stays consistent.
+- Model a **mode/source as a discriminated field, not a boolean flag**. `source: 'literal' |
+  'policy' | 'auto'` beats `useMatrix: boolean`: it's extensible (a third mode is a new enum
+  member, not a second conflicting flag), self-documenting, and makes contradictory inputs
+  (a literal payload sent with `source: 'policy'`) rejectable instead of silently dropped. If a
+  published boolean already exists, keep it as a `@deprecated` alias that bridges to the field
+  for one minor, then remove — don't strand consumers on a hard rename.
+
+---
+
+## Shape 2 — Plugin (cross-cutting decorator/hook)
+
+An `fp()`-wrapped Fastify plugin — the one documented exception to arc's no-default-exports
+rule. Ship **both** a default (for `app.register(import(...))`) and a named export.
+
+```ts
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+
+async function xPlugin(app: FastifyInstance /*, opts */): Promise<void> {
+  app.decorate("x", createX(/* ... */));
+  // Set response headers at onRequest or preSerialization — NEVER onSend (races Fastify's flush).
+}
+
+export const x = fp(xPlugin, { name: "arc-x", fastify: "5.x" });
+export default x;   // fp() plugin entries MAY default-export (arc convention exception)
+```
+
+Host registers it in the `plugins:` slot or via `app.register`. If the plugin belongs to a
+domain module, register it in the module's `plugins` lifecycle slot instead (below).
+
+---
+
+## Shape 3 — Module (a whole domain as one value)
+
+Use `defineModule` when there's engine state to boot **and** multiple resources to register as
+a unit. The host lists it in `createApp({ modules: [...] })`; arc expands it into the same
+lifecycle phases a hand-wired app uses.
+
+```ts
+import { defineModule, getModuleExports } from "@classytic/arc/factory";
+import type { FastifyInstance } from "fastify";
+
+export interface AccountingEngine { post(entry: Entry): Promise<void>; }
+export interface AccountingDeps { permissions: PermissionMatrix; }
+
+// Factory takes host deps, returns an ArcModule. TExports inferred from bootstrap's return.
+export const accountingModule = (deps: AccountingDeps) =>
+  defineModule({
+    name: "accounting",                 // namespaced, unique across the host — the graph key
+    dependsOn: ["ledger"],              // composition order (see below), NOT lazy loading
+
+    plugins: (f) => {                   // register infra — runs after app plugins(), before bootstraps
+      f.register(/* db conn, sse, etc. */);
+    },
+
+    bootstrap: async (f) => {           // init engine — its return becomes the PUBLIC EXPORT
+      const ledger = getModuleExports<LedgerEngine>(f, "ledger"); // guaranteed live (dependsOn)
+      return createAccountingEngine(deps, ledger);                // → fastify.arc.modules.accounting
+    },
+
+    resources: (f) => {                 // factory form runs AFTER all bootstraps — engines are live
+      const engine = getModuleExports<AccountingEngine>(f, "accounting");
+      return [accountsResource(engine, deps.permissions), entriesResource(engine)];
+    },
+
+    afterResources: (f) => { /* cross-resource event subscriptions the module owns */ },
+    onClose: (f) => { /* stop timers, flush outbox, destroy engine */ },
+
+    errorMappers: [{                    // 2.21 — domain error → wire envelope, merged into the
+      type: AccountingError,            // host's error handler at boot (host mappers keep priority)
+      toResponse: (err) => ({ status: err.status, code: err.code, message: err.message }),
+    }],
+  });
+```
+
+### Lifecycle phases (module runs before app-level in each)
+
+```
+plugins        = app plugins()          → modules' plugins        (infra registration)
+bootstrap[]    = modules' bootstrap      → options.bootstrap       (engine init + export)
+resources[]    = modules' resources      → options.resources        (module routes register first)
+afterResources = modules' afterResources → options.afterResources
+onClose        = modules' onClose (REVERSE order) → options.onClose  (last composed, first closed)
+```
+
+A module's engine is live before app-level bootstrap; app `afterResources` can wire across
+modules; teardown mirrors init in reverse.
+
+### `dependsOn` is composition order, not lazy loading
+
+`dependsOn: ["ledger"]` guarantees ledger's `plugins`/`bootstrap` (and thus its public export)
+run **before** this module's — so `getModuleExports(f, "ledger")` is live. It does **not** delay
+*importing* the module. Every module input (including dynamic-import thunks) is resolved up
+front via `Promise.all`, then `dependsOn` orders the *composition*. It's a **stable topological
+sort**: modules with no edge between them keep list order, so adding `dependsOn` never silently
+reorders an unrelated module. Fail-fast at boot on unknown dep, self-reference, and cycles.
+
+### Cross-module wiring — `getModuleExports`, not a container
+
+A module's `bootstrap` return value is its **public export**, recorded at
+`fastify.arc.modules[name]`. Later modules read it with the typed accessor — no DI container,
+no proxy. For inferred types without an inline generic, augment the registry once:
+
+```ts
+declare module "@classytic/arc/factory" {
+  interface ArcModuleRegistry {
+    accounting: AccountingEngine;
+    ledger: LedgerEngine;
+  }
+}
+// then: getModuleExports(f, "accounting") infers AccountingEngine
+```
+
+`getModuleExports` **throws** (fail-fast) if the name isn't composed, is composed after the
+caller, or returned nothing — all wiring bugs that must surface at boot, not as `undefined`
+downstream.
+
+### Lazy / region packs — thunk of a dynamic import
+
+To gate *whether* a module is imported at all (region/tier packs), pass a thunk that returns a
+dynamic import. Only the selected pack enters the bundle path:
+
+```ts
+const taxPack =
+  region === "BD"
+    ? () => import("@classytic/bd-tax").then((m) => m.createBdTaxModule(deps))
+    : () => import("@classytic/us-tax").then((m) => m.createUsTaxModule(deps));
+
+await createApp({ modules: [coreModule(deps), taxPack] });
+// only the selected tax package is imported + composed
+```
+
+Thunk = *whether to import*; `dependsOn` = *order of already-selected modules*. Different tools.
+
+### One module per package
+
+A package exports **one** `createXModule` factory. To compose several domains, publish several
+packages (or several subpath exports) and let the host list them — don't return an array of
+modules from one factory. The host owns the flat `modules:` list and its ordering; keep that
+control theirs.
+
+### Resource assembly — kernel-typed ports + `mergeResourceConfig` (2.21 standard)
+
+Two rules kill the `as never` tax that plagued pre-2.21 module packages:
+
+**1. Type the engine port with the KERNEL's own bags.** The kernel is already your peer, so
+indexing its exported engine type adds zero coupling — and its truths (optional sub-module
+members, literal unions) flow into your resource builders:
+
+```ts
+import type { CatalogEngine } from "@classytic/catalog";
+
+export interface CatalogEngineLike {          // structural — any conforming engine composes
+  models: CatalogEngine["models"];
+  repositories: CatalogEngine["repositories"];
+}
+```
+
+Never re-declare the bags as `Record<string, unknown>` — that's what forced every
+`createMongooseAdapter(engine.models.X as never, ...)` cast.
+
+**2. Merge base config + host seams with `mergeResourceConfig`, not hand-rolled spreads.**
+Expose your per-resource override surface as projections of arc's `ResourceSeams` and let
+arc's slot-aware merge do assembly — arrays CONCAT (host routes append, never clobber),
+plain objects deep-merge, class instances (queryParser, adapter) last-win, `undefined`
+never overwrites, `as const` readonly host tables are accepted:
+
+```ts
+import { defineResource, mergeResourceConfig, type ResourceSeams } from "@classytic/arc";
+import { permissionMatrix } from "@classytic/arc/permissions";
+
+export interface ProductSeams {               // your public seam names, arc's slot types
+  extraRoutes?: ResourceSeams["routes"];
+  extraActions?: ResourceSeams["actions"];
+  cache?: ResourceSeams["cache"];
+}
+
+defineResource(mergeResourceConfig(
+  {
+    name: "product",
+    adapter: createMongooseAdapter({ model: models.Product, repository: repositories.product }),
+    permissions: permissionMatrix({ read: deps.permissions.view, write: deps.permissions.manage }),
+  },
+  { routes: cfg.extraRoutes, actions: cfg.extraActions, cache: cfg.cache },
+));
+```
+
+The only casts left in a well-formed package are documented boundaries: wire-body narrowing
+in action handlers (`data as { role: PartyRole }` — narrow to the KERNEL's union, not
+`string`) and hydrated-vs-lean id widening at a kernel bridge. Anything else is a smell.
+
+---
+
+## Testing a package
+
+Boot a **real arc app** around your export and exercise it over HTTP — that's the only test
+that proves it *composes*. There are two harness layers, and the difference matters:
+
+| Harness | Persistence | Fidelity | Home |
+|---|---|---|---|
+| `@classytic/arc/testing` | none — you inject a repo (fake / `Map`-backed) | boot + wiring only | inside arc |
+| a **kit-backed testkit** (e.g. `@classytic/arc-testkit`) | real in-memory store (Mongo memory-server) | **prod-fidelity** | arc-ecosystem |
+
+**Why two layers, and why the testkit is kit-specific:** arc's non-negotiable rule is *no DB
+driver imports anywhere in arc*. So `@classytic/arc/testing` can boot the app but cannot give
+you real persistence — it hands you an injected/fake repository. A harness that persists for
+real **must** pick a concrete kit (mongokit + `mongodb-memory-server`, or sqlite in-memory).
+That's not a limitation to design around — it's the point: **a testkit's value is fidelity, so
+it should exercise the module the way it runs in production**, with the same adapter.
+
+**Don't "make the testkit DB-agnostic" by defaulting to a fake in-memory repo.** A `Map`-backed
+repo does not reproduce ObjectId-vs-string `_id`, `select`/projection semantics, query-operator
+translation, pagination cursor encoding, unique-index enforcement, or Mongoose strict-mode
+field dropping. A module that ships a real adapter will pass on the fake and break in prod — the
+test gets greener and less truthful. Agnostic *interface*, real *backend*:
+
+- **Agnostic seam:** the harness takes a **`TestBackend`** — `setup() → { ctx: { connection,
+  uri }, teardown }` — so the store is pluggable, not hard-wired.
+- **Real default, backend lives in the kit:** `@classytic/arc-testkit` is the thin generic core
+  (`bootModuleApp(modules, { backend })`); its default backend is `mongoMemoryBackend()` from
+  **`@classytic/mongokit/testkit`**, loaded via dynamic `import()` so mongokit +
+  `mongodb-memory-server` stay *optional* peers. This is the concrete "adapters/backends live in
+  their kits" split — mongokit owns the Mongo lifecycle, arc-testkit owns the arc boot. Add a
+  sibling (`@classytic/sqlitekit/testkit` → `sqliteMemoryBackend()`) only when a non-Mongo module
+  exists — YAGNI until the second consumer is real.
+
+```ts
+import { bootModuleApp } from "@classytic/arc-testkit";
+import { mongoMemoryBackend } from "@classytic/mongokit/testkit"; // only to override the default
+
+const t = await bootModuleApp(({ connection }) => [createOrderModule({ connection, permissions })]);
+// or point at a real cluster:  { backend: mongoMemoryBackend({ uri: process.env.ATLAS_TEST_URI }) }
+const res = await t.app.inject({ method: "GET", url: "/orders" });
+await t.close();
+```
+
+**Install contract (the part that bites on adoption):** because the harness declares its DB deps
+as *optional peers*, the consumer installs all three together —
+
+```bash
+npm i -D @classytic/arc-testkit @classytic/mongokit mongodb-memory-server
+```
+
+Miss `mongodb-memory-server` and the default backend throws at boot; pin `@classytic/mongokit`
+below the version that first shipped `/testkit` and the subpath won't resolve (a floating `^`
+range won't upgrade past a lockfile pin on its own — bump the devDep floor). This is the tradeoff
+of *not* bundling: the harness stays out of production, but the consumer owns the dev install.
+
+Whichever layer you use, cover these edges:
+
+- Boot a minimal app, register your preset/module, hit the routes with `app.inject`.
+- Test **both tenancy modes** (`required` and `off`) if you support them.
+- Avoid field names arc's query parser reserves (`page`, `limit`, `cursor`, `after`, `sort`,
+  `search`, `select`, `populate`) — a filter field colliding with one is silently unfilterable.
+  Arc emits a `filter-field-reserved-name` boot diagnostic; heed it. **This class of bug only
+  surfaces on a real backend** — another reason the fidelity harness earns its keep.
+- Pin devDeps at or above every peer floor so the suite exercises the version you promise.
+
+**Shared harness pattern:** the harness is published once — `@classytic/arc-testkit` (generic
+core, in the ecosystem repo, *not* a per-domain monorepo) + `@classytic/mongokit/testkit` (the
+Mongo backend, in the kit) — so every module author and third party reuses it. Depend on it via
+`devDependencies` (a version range from the registry; `workspace:*` only inside its own monorepo).
+"If your module boots green in the testkit, it composes" is the contract.