cvx-kit 0.1.5 → 0.1.7

package/docs/effect.md

@@ -0,0 +1,384 @@
+# Effect domain commands and queries
+
+`cvx-kit/effect` adds cohesive command/query declarations and a shared API
+runner. Handlers can return ordinary values, Promises, or Effects. Each
+registry returns a lazy Effect from `exec(operation, input, host)`; the API
+adapter provides request services and runs it once.
+
+Install Effect explicitly when opting in:
+
+```sh
+bun add effect@4.0.1
+```
+
+The optional peer range is `>=4.0.1 <5`. Existing imports and Promise-based
+Foundation consumers work without Effect installed. Use the public facade;
+the internal module paths are not supported imports.
+
+## A complete domain-to-API example
+
+These four TypeScript sections form one module and are compiled together
+against the packed public package. The example uses Convex's generic builders
+with a concrete schema so it is standalone. In an app, put the schema in
+`convex/schema.ts`, import your generated `query`, `mutation`, `QueryCtx`, and
+`MutationCtx` from `./_generated/server`, and split the remaining code into
+services, domain registries, shared API setup, and endpoint modules.
+
+The API obtains the actor from authenticated Convex identity. Caller arguments
+contain only a document key and title. Both services constrain document reads
+and writes by that actor; the application should also enforce its own roles
+and tenant policies. The small permission checker below only requires a
+nonempty trusted actor.
+
+### Contracts and injectable capabilities
+
+The reader has no write methods. The mutation provider will add the writer;
+a native query cannot satisfy a command's writer requirement. Expected errors
+are values in the Effect error channel, rather than thrown exceptions.
+
+```ts
+import { Context, Effect } from 'effect'
+import {
+	defineSchema,
+	defineTable,
+	queryGeneric,
+	mutationGeneric,
+	type DataModelFromSchemaDefinition,
+	type QueryBuilder,
+	type MutationBuilder,
+	type GenericQueryCtx,
+	type GenericMutationCtx,
+} from 'convex/server'
+import { ConvexError, v } from 'convex/values'
+import { z } from 'zod'
+import { createEffectFoundation, effectApiBuilder } from 'cvx-kit/effect'
+import type { AuditEntryInput } from 'cvx-kit/components/foundation'
+
+export const schema = defineSchema({
+	documents: defineTable({ key: v.string(), owner: v.string(), title: v.string() }).index(
+		'by_owner_key',
+		['owner', 'key'],
+	),
+	audits: defineTable({ actor: v.string(), operation: v.string(), documentKey: v.string() }),
+})
+type DataModel = DataModelFromSchemaDefinition<typeof schema>
+type QueryCtx = GenericQueryCtx<DataModel>
+type MutationCtx = GenericMutationCtx<DataModel>
+const nativeQuery: QueryBuilder<DataModel, 'public'> = queryGeneric
+const nativeMutation: MutationBuilder<DataModel, 'public'> = mutationGeneric
+
+type Host = { actor: string }
+class DocumentMissing {
+	readonly _tag = 'DocumentMissing'
+}
+class RenameRejected {
+	readonly _tag = 'RenameRejected'
+}
+class AccessDenied {
+	readonly _tag = 'AccessDenied'
+}
+class DocumentReader extends Context.Service<
+	DocumentReader,
+	{ title: (key: string, actor: string) => Effect.Effect<string, DocumentMissing> }
+>()('DocumentReader') {}
+class DocumentWriter extends Context.Service<
+	DocumentWriter,
+	{
+		rename: (key: string, title: string, actor: string) => Effect.Effect<void, DocumentMissing>
+		audit: (actor: string, entry: AuditEntryInput) => Effect.Effect<void>
+	}
+>()('DocumentWriter') {}
+```
+
+### Cohesive domain declarations
+
+`label` is an ordinary async handler, and `preview` uses a generator. `title` uses `Effect.fn` with explicit input
+and host annotations. `rename` returns an `Effect.gen` program, yields the
+query directly, then uses the injected writer. Its pipe converts the query's
+missing-document error into a domain-specific rename rejection before adding
+a span. The audit entry sits beside the command, and the shared audit policy
+uses the same invocation's writer.
+
+```ts
+const foundation = createEffectFoundation({
+	observability: {
+		enabled: false,
+		classifyError: () => ({ outcome: 'failed' as const, errorCode: 'DOCUMENT_OPERATION_FAILED' }),
+	},
+	checkPermission: (host: Host) =>
+		host.actor.length > 0 ? Effect.void : Effect.fail(new AccessDenied()),
+	writeAudit: (host: Host, entry: AuditEntryInput) =>
+		Effect.gen(function* () {
+			const writer = yield* DocumentWriter
+			yield* writer.audit(host.actor, entry)
+		}),
+})
+const keyInput = z.object({ key: z.string().min(1) })
+const renameInput = keyInput.extend({ title: z.string().trim().min(1) })
+const titleResult = z.string().transform((title) => ({ title }))
+
+export const documents = foundation.Query({
+	context: (host: Host) => host,
+	operations: ({ query }) => ({
+		label: query({
+			input: keyInput,
+			result: z.string(),
+			handler: async (input) => `Document ${input.key}`,
+		}),
+		preview: query({
+			input: keyInput,
+			result: titleResult,
+			permission: 'documents:read',
+			handler: (input, host) =>
+				Effect.gen(function* () {
+					const reader = yield* DocumentReader
+					return yield* reader.title(input.key, host.actor)
+				}),
+		}),
+		title: query({
+			input: keyInput,
+			result: titleResult,
+			permission: 'documents:read',
+			handler: Effect.fn('documents.title')(function* (
+				input: z.output<typeof keyInput>,
+				host: Host,
+			) {
+				const reader = yield* DocumentReader
+				return yield* reader.title(input.key, host.actor)
+			}),
+		}),
+	}),
+})
+export const documentCommands = foundation.Command({
+	context: (host: Host) => host,
+	operations: ({ command }) => ({
+		rename: command({
+			input: renameInput,
+			result: titleResult,
+			classification: 'business',
+			permission: 'documents:write',
+			handler: (input, host) =>
+				Effect.gen(function* () {
+					// A nested query stays in the same Effect; no inner runner.
+					yield* documents.exec('title', { key: input.key }, host)
+					const writer = yield* DocumentWriter
+					yield* writer.rename(input.key, input.title, host.actor)
+					return input.title
+				}).pipe(
+					Effect.catchTag('DocumentMissing', () => Effect.fail(new RenameRejected())),
+					Effect.withSpan('documents.rename'),
+				),
+			guard: (host) => (host.actor.length > 0 ? Effect.void : Effect.fail(new AccessDenied())),
+			middleware: ({ next }) => next().pipe(Effect.withSpan('documents.command')),
+			audit: ({ command: input, result }, host) => ({
+				actorId: host.actor,
+				operation: 'documents.rename',
+				aggregate: { type: 'document', id: input.key },
+				metadata: { title: result.title },
+			}),
+		}),
+	}),
+})
+```
+
+### Request services and shared API setup
+
+Construct the services once in each shared builder provider. Endpoint handlers
+do not call `Context.make`, `Effect.runPromise`, or an extra execution helper.
+The database Promise wrappers below intentionally preserve unexpected database
+failures as defects. For external integrations with expected failures, use
+`Effect.tryPromise` and return your own typed error.
+
+`mapError` projects an expected failure to a small `ConvexError` payload. It
+receives `unknown`, so narrow it before projection. Defects, interruption,
+and combined causes do not become expected failures through this hook; the
+adapter preserves those failure causes. The registered function still fails,
+which is required for mutation rollback.
+
+```ts
+function readerFor(ctx: QueryCtx): Context.Context<DocumentReader> {
+	return Context.make(DocumentReader, {
+		title: (key, actor) =>
+			Effect.gen(function* () {
+				const document = yield* Effect.promise(() =>
+					ctx.db
+						.query('documents')
+						.withIndex('by_owner_key', (q) => q.eq('owner', actor).eq('key', key))
+						.unique(),
+				)
+				if (!document) return yield* Effect.fail(new DocumentMissing())
+				return document.title
+			}),
+	})
+}
+function writerFor(ctx: MutationCtx): Context.Context<DocumentWriter> {
+	return Context.make(DocumentWriter, {
+		rename: (key, title, actor) =>
+			Effect.gen(function* () {
+				const document = yield* Effect.promise(() =>
+					ctx.db
+						.query('documents')
+						.withIndex('by_owner_key', (q) => q.eq('owner', actor).eq('key', key))
+						.unique(),
+				)
+				if (!document) return yield* Effect.fail(new DocumentMissing())
+				yield* Effect.promise(() => ctx.db.patch(document._id, { title }))
+			}),
+		audit: (actor, entry) =>
+			Effect.promise(() =>
+				ctx.db.insert('audits', {
+					actor,
+					operation: entry.operation,
+					documentKey: entry.aggregate.id,
+				}),
+			).pipe(Effect.asVoid),
+	})
+}
+function authenticatedHost(ctx: QueryCtx) {
+	return Effect.gen(function* () {
+		const identity = yield* Effect.promise(() => ctx.auth.getUserIdentity())
+		if (!identity) return yield* Effect.fail(new AccessDenied())
+		return { actor: identity.tokenIdentifier }
+	})
+}
+function projectExpectedError(error: unknown) {
+	if (error instanceof DocumentMissing || error instanceof RenameRejected)
+		return new ConvexError({ code: 'DOCUMENT_NOT_FOUND' })
+	if (error instanceof AccessDenied) return new ConvexError({ code: 'ACCESS_DENIED' })
+	return new Error('Document operation failed', { cause: error })
+}
+const queryApi = effectApiBuilder(nativeQuery, {
+	services: readerFor,
+	mapError: projectExpectedError,
+})
+const mutationApi = effectApiBuilder(nativeMutation, {
+	services: (ctx) => Context.merge(readerFor(ctx), writerFor(ctx)),
+	mapError: projectExpectedError,
+})
+```
+
+### Consume the domain operations in the API
+
+The Convex callback remains `(ctx, input)`; the domain callback and executor
+use input before context/host. Both endpoints are normal native registrations
+with argument and return validators. Each handler authenticates the request
+and returns the domain Effect. The adapter supplies the services required by
+the complete nested program.
+
+```ts
+export const documentTitle = queryApi({
+	args: { key: v.string() },
+	returns: v.object({ title: v.string() }),
+	handler: (ctx, input) =>
+		Effect.gen(function* () {
+			const host = yield* authenticatedHost(ctx)
+			return yield* documents.exec('title', input, host)
+		}),
+})
+export const renameDocument = mutationApi({
+	args: { key: v.string(), title: v.string() },
+	returns: v.object({ title: v.string() }),
+	handler: (ctx, input) =>
+		Effect.gen(function* () {
+			const host = yield* authenticatedHost(ctx)
+			return yield* documentCommands.exec('rename', input, host)
+		}),
+})
+```
+
+## Types and schema boundaries
+
+The command accepts `z.input<typeof renameInput>`. Its handler sees
+`z.output<typeof renameInput>`, so the title has already been trimmed. The
+handler returns a string, which is the input of `titleResult`; the registry's
+final result is `{ title: string }`, the output of that transform. Middleware
+`next()` returns the handler result before the final result parser, so wrap
+or transform that value according to the result schema's input contract.
+
+TypeScript preserves the selected operation's success, expected error, and
+service requirements. The title query requires `DocumentReader`; rename
+requires `DocumentReader | DocumentWriter` and can fail with `AccessDenied`
+or `RenameRejected`. The API builder checks that its provider supplies those
+services. A reader-only provider cannot register rename, and an incompatible
+handler result cannot pass its declared native return validator.
+
+This is server-side Effect composition. Generated Convex references retain
+native argument/result types and visibility; they do not carry Effect's typed
+error or service channels over the transport. Clients receive ordinary Convex
+results or errors.
+
+For inferred declarations, put `handler` and `guard` before `middleware`, as
+above. Middleware-first declarations need explicit callback and error/service
+annotations where inference cannot recover the later handler's channels.
+`Effect.fn` accepts typed function arguments; `Effect.gen` accepts a generator
+whose yielded Effects determine its channels. Use `(input, context) =>
+Effect.gen(function* () { ... })` when those values come from the declaration.
+A constructed `Effect.gen` program cannot itself receive handler arguments.
+
+## Hooks, replay, and execution scope
+
+A command runs input parsing, observation setup and context resolution, then
+permission checking, preparation, middleware, shared and operation guards,
+handler, final result parsing, audit construction, aggregate checking, audit
+writing, and completion. Observation records the outcome. Query permission
+checking runs before its context resolver, followed by middleware, guards,
+handler, and result parsing. Command audit/completion hooks do not exist on
+queries.
+
+Optional command `prepare(context, input)` returns `{ kind: 'execute',
+complete }` or `{ kind: 'replay', result }`. The completion callback receives
+the parsed final result. Permission checking still precedes replay. A replay
+result is parsed with `replayResult` when supplied, otherwise with `result`,
+and skips middleware, guards, handler, audit writing, and completion.
+Middleware receives `operation`, parsed `input` (also `command`), `context`,
+and `next`; it may provide an enriched context to `next({ context })`.
+Each execution allows `next` once. Audit construction sees the original domain
+context, and the audit writer sees the original trusted host.
+
+The provider may return a `Context`, a Promise of a Context, or an Effect that
+builds a Context. It runs separately for every native invocation. The shared
+runner opens an Effect scope, evaluates the provider and handler, and awaits
+scope finalizers before returning or throwing. Use `Effect.acquireRelease`
+inside a provider for resources that actually need cleanup. Nested domain
+operations share that runner and scope; do not run them independently inside
+handlers. Cleanup failure remains an endpoint failure, including when it
+combines with a handler failure.
+
+## Convex boundaries and observed support
+
+A domain query is a reusable read operation; its name does not choose the
+native function kind. A native Convex query must perform deterministic database
+reads. Native mutations can write, and a failed command, result validator,
+audit writer, completion hook, or awaited cleanup rolls back that mutation's
+writes. Actions are the place for HTTP and other external integrations.
+An action's separate `ctx.runMutation` calls are separate transactions: a
+later failure does not undo an earlier successful mutation.
+
+The packed public facade was compiled and executed under npm and Bun with
+Effect 4.0.1 and `convex-helpers` 0.1.123. Legacy packed consumers also ran with
+Effect absent. Local Convex 1.45.0 checks exercised ordinary, generator, and
+named-function query composition; request cleanup; expected and combined
+failures; mutation validation and lifecycle rollback; and an action using
+loopback HTTP with separate mutation transactions. `Effect.withSpan` was
+accepted in those programs; this does not establish exported telemetry,
+background fibers, arbitrary concurrency, or every Effect runtime capability
+in Convex.
+
+The standalone packed compiler includes `ESNext.Disposable` in its library
+set for Effect 4 declarations. If your project's TypeScript environment does
+not already provide those globals, include that library as well.
+
+## Adopt one domain at a time
+
+Keep existing Promise registries and API endpoints while adding the optional
+facade for a new domain. Move each operation's handler beside its schemas and
+hooks, switch domain callbacks to input-first arguments, and return the new
+registry's lazy Effect to a shared API adapter. A normal async handler works
+in the cohesive declaration without a generator; wrap expected Promise failures
+only when you want a typed error channel.
+
+The [command migration guide](./commands.md) shows a complete legacy-to-Effect
+pair and the existing lifecycle contract. The [authentication guide](./auth.md)
+shows how to wrap trusted custom builders with `effectZodApiBuilder`, so auth,
+tenancy, validators, row-level policies, and triggers run through their
+existing builder before Effect request services are provisioned.

package/docs/oxlint.md

@@ -5,8 +5,8 @@ checks applications using the kit against `conventions.md`, the authoritative
 source for folder structure and file anatomy. The package repository has a
 separate, unpublished plugin for its own `src/` layout.
 
-These consumer rules are available from 0.1.5; the initial 0.1.4 plugin targeted
-library authoring. See `upgrading.md` when migrating that configuration.
+The consumer plugin was introduced in 0.1.5; the initial 0.1.4 plugin targeted
+library authoring. The five architecture rules below were added in 0.1.6. See `upgrading.md` when migrating that configuration.
 
 ## Configuration
 
@@ -36,31 +36,36 @@ For another location, set `convexDir` on **each enabled rule**:
 { "cvx/no-raw-builders": ["error", { "convexDir": "src/server/convex" }] }
 ```
 
-Rules ignore files outside that directory, `_generated/`, `__tests__/`, and
-files ending in `.test` or `.spec` before their JS/TS extension. They do not
+Source rules ignore files outside that directory, `_generated/`, `__tests__/`,
+and test/spec files. `project-structure` reads the whole backend, including tests. They do not
 offer automatic fixes for architectural moves.
 
 ## Coverage
 
 Every name below has the `cvx/` prefix in lint configuration.
 
-| Rule                        | Detects                                                                                                                                          | Documentation                                   |
-| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
-| `root-facade-ownership`     | `createAuthFunctions`, `createTriggers`, and `new Foundation` outside their root files, or repeated in one file.                                 | `conventions.md`, Root files                    |
-| `no-raw-builders`           | Runtime imports of raw Convex builders outside `functions.ts`; namespace calls to raw generic builders.                                          | `auth.md`; `llms.md`, Non-negotiable rules      |
-| `no-handwritten-references` | Calls to Convex `makeFunctionReference`, including import aliases.                                                                               | `conventions.md`, Import rules                  |
-| `domain-import-boundaries`  | Reverse dependencies into `api/`, domain imports of `application/`, forbidden sibling imports, and API adapters importing another domain module. | `conventions.md`, Module grain and Import rules |
-| `public-functions-in-api`   | Calls to root `auth*`, `role*`, or `admin*` constructors outside `api/`.                                                                         | `conventions.md`, Folder structure              |
-| `thin-api-adapters`         | `if`, `switch`, ternary branches, top-level private helpers, and direct `ctx.db` writes in `api/`.                                               | `conventions.md`, The adapter file              |
-| `no-inline-enums`           | Literal arrays passed to imported Zod `enum`. Use named vocabulary tuples.                                                                       | `conventions.md`, Vocabularies                  |
-| `no-unbounded-reads`        | Direct `ctx.db.query(...).collect()` chains and `ctx.include(...).resolve()` chains in host code.                                                | `llms.md`, Bounded reads; `zod-table.md`        |
-| `no-manual-timestamps`      | Explicit `createdAt`/`updatedAt` fields in object literals passed to direct `ctx.db` writes.                                                     | `triggers.md`                                   |
-| `component-boundaries`      | Local portable components importing host/sibling files; host imports bypassing component client facades; private package component subpaths.     | `architecture.md`, Injection, not import        |
-| `no-component-env`          | Direct `process.env` access, process import aliases, environment destructuring, and named env imports inside local portable components.          | `conventions.md`, Import rules                  |
-| `schema-file-boundaries`    | Host `defineTable`, misplaced `defineSchema` or kit table constructors, and misplaced `.table.index/searchIndex/vectorIndex` chains.             | `conventions.md`, Shapes and topology           |
-| `no-internal-reexports`     | Re-exports and import-then-export aliases inside `convex/`.                                                                                      | `conventions.md`, Universal file order          |
-| `public-api-first`          | Private function declarations before the last export.                                                                                            | `conventions.md`, Universal file order          |
-| `named-private-helpers`     | Top-level private arrow/function-expression variables.                                                                                           | `conventions.md`, Universal file order          |
+| Rule                           | Detects                                                                                                                                                                                               | Documentation                                   |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
+| `project-structure`            | Root folder allowlist, domain ownership, colocated runnable tests, misplaced tests, symlinks, parse failures, runtime domain-module cycles, and shared implementations with only one domain consumer. | Folder structure and Tests                      |
+| `root-wiring-only`             | Unknown root files without a component facade, root function declarations, nondelegating callbacks, branches, loops, direct writes/network calls, and inline root schema construction.                | Root files                                      |
+| `application-orchestration`    | Files without two domain dependencies, provider construction, external runtime dependencies, database access, validator construction, and business branches.                                          | Module grain                                    |
+| `internal-function-ownership`  | Internal/system registrations at root, in public API adapters, or in domain/shared.                                                                                                                   | Folder structure                                |
+| `domain-file-responsibilities` | Impure rules, query writes/mutations, database access in declarative files, misplaced direct external I/O, and imports that violate these roles.                                                      | File anatomy                                    |
+| `root-facade-ownership`        | `createAuthFunctions`, `createTriggers`, and `new Foundation` outside their root files, or repeated in one file.                                                                                      | `conventions.md`, Root files                    |
+| `no-raw-builders`              | Runtime imports of raw Convex builders outside `functions.ts`; namespace calls to raw generic builders.                                                                                               | `auth.md`; `llms.md`, Non-negotiable rules      |
+| `no-handwritten-references`    | Calls to Convex `makeFunctionReference`, including import aliases.                                                                                                                                    | `conventions.md`, Import rules                  |
+| `domain-import-boundaries`     | Reverse dependencies into `api/`, domain imports of `application/`, forbidden sibling imports, and API adapters importing another domain module.                                                      | `conventions.md`, Module grain and Import rules |
+| `public-functions-in-api`      | Calls to root `auth*`, `role*`, or `admin*` constructors outside `api/`.                                                                                                                              | `conventions.md`, Folder structure              |
+| `thin-api-adapters`            | `if`, `switch`, ternary branches, top-level private helpers, and direct `ctx.db` writes in `api/`.                                                                                                    | `conventions.md`, The adapter file              |
+| `no-inline-enums`              | Literal arrays passed to imported Zod `enum`. Use named vocabulary tuples.                                                                                                                            | `conventions.md`, Vocabularies                  |
+| `no-unbounded-reads`           | Direct `ctx.db.query(...).collect()` chains and `ctx.include(...).resolve()` chains in host code.                                                                                                     | `llms.md`, Bounded reads; `zod-table.md`        |
+| `no-manual-timestamps`         | Explicit `createdAt`/`updatedAt` fields in object literals passed to direct `ctx.db` writes.                                                                                                          | `triggers.md`                                   |
+| `component-boundaries`         | Local portable components importing host/sibling files; host imports bypassing component client facades; private package component subpaths.                                                          | `architecture.md`, Injection, not import        |
+| `no-component-env`             | Direct `process.env` access, process import aliases, environment destructuring, and named env imports inside local portable components.                                                               | `conventions.md`, Import rules                  |
+| `schema-file-boundaries`       | Host `defineTable`, misplaced `defineSchema` or kit table constructors, and misplaced `.table.index/searchIndex/vectorIndex` chains.                                                                  | `conventions.md`, Shapes and topology           |
+| `no-internal-reexports`        | Re-exports and import-then-export aliases inside `convex/`.                                                                                                                                           | `conventions.md`, Universal file order          |
+| `public-api-first`             | Private function declarations before the last export.                                                                                                                                                 | `conventions.md`, Universal file order          |
+| `named-private-helpers`        | Top-level private arrow/function-expression variables.                                                                                                                                                | `conventions.md`, Universal file order          |
 
 ## Allowed patterns
 
@@ -69,7 +74,8 @@ Every name below has the `cvx/` prefix in lint configuration.
   elsewhere. `httpAction` remains available for HTTP routing.
 - Domain modules may import sibling `rules.ts` and `queries.ts`, as explicitly
   allowed by the module-grain section. Cross-module writes go through the
-  optional `application/` layer. `domain/table.ts` combines module table maps.
+  optional `application/` layer. `domain/table.ts` only imports module table maps
+  and combines them with `createModule` from `cvx-kit/zod-table`.
 - API adapters may delegate and perform the documented bounded inline query
   and DTO projection. `system*` constructors may live in domain modules.
 - Authored components under `convex/components/<name>/` may use their own raw
@@ -84,8 +90,9 @@ Every name below has the `cvx/` prefix in lint configuration.
 ## What still needs review and tests
 
 These are syntax and lexical-binding checks, not whole-program validation.
-They resolve relative import paths, not tsconfig aliases, symlinks, or computed
-paths. Named import aliases and namespaces are recognized where documented;
+Import-boundary rules resolve relative imports and tsconfig aliases (including
+extended configs) using the package resolver. Symlinked source is rejected by
+the project scan. Computed import paths are not resolved. Named import aliases and namespaces are recognized where documented;
 arbitrary variable reassignment, wrapper functions, destructured database
 methods, and calls split across variables are not traced. Database checks
 recognize the documented `ctx.db` member shape, not its runtime type.
@@ -93,6 +100,47 @@ recognize the documented `ctx.db` member shape, not its runtime type.
 The plugin does not prove DTO redaction, complete command/audit coverage,
 tenant/RLS correctness, unique table ownership across files, required facade
 existence, exactly one component mount, numeric read limits, or vocabulary
-tuple ownership. Keep the architecture tests from `conventions.md` and the
-behavioral tests described in `maintainability.md`. A clean lint run is not
+tuple ownership. Run the behavioral tests described in `maintainability.md`. The package owns
+structural enforcement; applications do not need copied architecture tests. A clean lint run is not
 evidence of those runtime guarantees.
+
+## Whole-project validation
+
+Enable `cvx/project-structure` and lint the **whole** configured backend. The
+scan reports on `convex.config.ts`, or the first non-test source file if no
+configuration file exists. That anchor must be part of the lint invocation;
+changed-file-only runs and cached lint runs can skip project checks. Use a full,
+uncached lint run in CI. The scan ignores generated code, reads current files on
+every invocation, and does not execute application code.
+
+For standalone tooling, including an empty/missing backend, use the same packaged
+checker directly:
+
+```ts
+import { checkArchitecture } from 'cvx-kit/oxlint'
+
+const issues = checkArchitecture({ cwd: process.cwd(), convexDir: 'convex' })
+for (const issue of issues) console.error(`${issue.file}: ${issue.message}`)
+if (issues.length) process.exitCode = 1
+```
+
+No fixed module scaffold is required. Type-only modules and grouping folders
+need no test directory. Runtime schema/constants files do; root wiring shares
+root tests. Test files must be directly inside the owning `__tests__/` directory.
+Recognized test entrypoints are `test`/`it` globals and imports from Vitest,
+Vite+, Bun, Node, or Jest, including import aliases and namespaces. Empty,
+TODO, skipped, and conditionally skipped/run tests do not satisfy the minimum.
+A nonempty callback is a presence check, not evidence of meaningful assertions,
+execution, or coverage. Run the tests in CI.
+
+Cycle detection operates on runtime ESM imports/re-exports and literal dynamic
+imports between `domain/<module>` owners, including nested files. Type-only
+imports do not create runtime cycle edges. Arbitrary CommonJS wrappers, computed
+imports, implicit generated function-reference calls, and value flow are not
+whole-program analyzed. Rules report recognizable violations; clean lint does
+not prove arbitrary business logic is absent.
+
+Shared ownership follows static runtime imports through shared helpers. A shared
+file reached from only one domain is reported for relocation. Unused code,
+type-only consumers, and computed dependencies are not treated as proof of shared
+ownership; their ownership still needs review.

package/docs/upgrading.md

@@ -1,5 +1,18 @@
 # Upgrading to 0.1.0 — the new way of things
 
+## 0.1.6 — stricter architecture checks
+
+Enable `project-structure`, `root-wiring-only`, `application-orchestration`,
+`internal-function-ownership`, and `domain-file-responsibilities` alongside the
+existing rules. These are opt-in additions; existing enabled boundary rules now
+also resolve tsconfig aliases and reject migration dependencies.
+
+Move root implementation folders into their owning domains. Keep `application/`
+limited to multi-domain coordination. Move centralized domain tests beside their
+owners and add real tests for nested executable directories. Do not create empty
+scaffold files. Replace copied structural architecture suites with the packaged
+checks; retain tests that exercise actual application behavior and wiring.
+
 ## 0.1.5 — consumer Oxlint rules
 
 The initial 0.1.4 plugin incorrectly targeted this package's `src/` layout.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cvx-kit",
-	"version": "0.1.5",
+	"version": "0.1.7",
 	"description": "Reusable Convex application kit: foundation kernels, approvals component, zod table boundaries, WorkOS-backed auth function constructors, and audited command protocol.",
 	"keywords": [
 		"component",
@@ -30,6 +30,22 @@
 			"types": "./dist/zod-table.d.mts",
 			"import": "./dist/zod-table.mjs"
 		},
+		"./effect": {
+			"types": "./dist/effect.d.mts",
+			"import": "./dist/effect.mjs"
+		},
+		"./contracts": {
+			"types": "./dist/contracts.d.mts",
+			"import": "./dist/contracts.mjs"
+		},
+		"./idempotency": {
+			"types": "./dist/idempotency.d.mts",
+			"import": "./dist/idempotency.mjs"
+		},
+		"./workflow": {
+			"types": "./dist/workflow.d.mts",
+			"import": "./dist/workflow.mjs"
+		},
 		"./auth": {
 			"types": "./dist/auth.d.mts",
 			"import": "./dist/auth.mjs"
@@ -109,13 +125,15 @@
 	"scripts": {
 		"lint": "vp lint",
 		"check": "vp check",
-		"test:lint": "vp test run tools/oxlint/cvx/index.test.mjs",
+		"test:lint": "vp test run tools/oxlint/cvx",
 		"build": "vp pack && node scripts/convex-config-bridge.mjs && publint",
 		"typecheck": "tsc --noEmit",
 		"test": "vp test run --exclude test/package-contents.test.mjs",
 		"test:package": "bun run build && vp test run test/package-contents.test.mjs",
 		"test:package:ids": "bun run build && node scripts/test-packed-ids.mjs",
 		"test:package:oxlint": "bun run build && node scripts/test-packed-oxlint.mjs",
+		"test:package:effect": "bun run build && node scripts/test-packed-effect.mjs",
+		"test:package:smoke:effect": "bun run build && node scripts/smoke-packed-effect.mjs",
 		"test:package:smoke:bun": "bun scripts/smoke-packed-components.mjs bun",
 		"test:package:smoke:npm": "node scripts/smoke-packed-components.mjs npm",
 		"docs:sync": "rm -f docs/*.md && cp src/docs/*.md docs/",
@@ -127,7 +145,9 @@
 	"dependencies": {
 		"@convex-dev/workflow": "0.4.6",
 		"@oxlint/plugins": "1.79.0",
-		"convex-audit-log": "^0.2.0"
+		"convex-audit-log": "^0.2.0",
+		"oxc-parser": "0.150.0",
+		"oxc-resolver": "11.24.2"
 	},
 	"devDependencies": {
 		"@edge-runtime/vm": "^5.0.0",
@@ -135,6 +155,7 @@
 		"convex": "1.45.0",
 		"convex-helpers": "0.1.124",
 		"convex-test": "^0.0.56",
+		"effect": "4.0.1",
 		"oxlint": "1.79.0",
 		"publint": "^0.3.24",
 		"typescript": "7.0.2",
@@ -144,6 +165,19 @@
 	"peerDependencies": {
 		"convex": "^1.45.0",
 		"convex-helpers": ">=0.1.123 <0.2.0",
+		"effect": ">=4.0.1 <5",
 		"zod": "^4.5.4"
+	},
+	"peerDependenciesMeta": {
+		"effect": {
+			"optional": true
+		}
+	},
+	"devEngines": {
+		"packageManager": {
+			"name": "bun",
+			"version": "1.4.2",
+			"onFail": "download"
+		}
 	}
 }