@classytic/arc 2.8.5 → 2.10.3

package/README.md

@@ -2,7 +2,7 @@
 
 Database-agnostic resource framework for Fastify. Define resources, get CRUD routes, permissions, presets, caching, events, OpenAPI, and MCP tools — without boilerplate.
 
-**v2.8.4** | Fastify 5+ | Node.js 22+ | ESM only | 279+ test files, 3867+ tests
+**v2.10** | Fastify 5+ | Node.js 22+ | ESM only
 
 ## Install
 
@@ -65,8 +65,15 @@ const app = await createApp({
 Clean DX without growing exclude lists:
 
 ```typescript
-// app.ts — register once with perResource mode
-await fastify.register(auditPlugin, { autoAudit: { perResource: true } });
+import { Repository, methodRegistryPlugin, batchOperationsPlugin } from '@classytic/mongokit';
+
+// app.ts — pass any RepositoryLike (mongokit / prismakit / custom)
+await fastify.register(auditPlugin, {
+  autoAudit: { perResource: true },
+  // batchOperationsPlugin enables deleteMany, required for purgeOlderThan()
+  repository: new Repository(AuditModel, [methodRegistryPlugin(), batchOperationsPlugin()]),
+  // or omit `repository` for in-memory dev
+});
 
 // order.resource.ts — opt in
 defineResource({ name: 'order', audit: true });
@@ -99,8 +106,8 @@ const productResource = defineResource({
     delete: roles('admin'),
   },
   cache: { staleTime: 30, gcTime: 300, tags: ['catalog'] }, // QueryCache (opt-in)
-  additionalRoutes: [
-    { method: 'GET', path: '/featured', handler: 'getFeatured', permissions: allowPublic(), wrapHandler: true },
+  routes: [
+    { method: 'GET', path: '/featured', handler: 'getFeatured', permissions: allowPublic() },
   ],
 });
 
@@ -383,6 +390,29 @@ await app.events.subscribe('order.*', async (event) => { ... });
 
 CRUD events (`product.created`, `product.updated`, `product.deleted`) emit automatically.
 
+### Causation Chains & DLQ (v2.9)
+
+```typescript
+import { createEvent, createChildEvent, type DeadLetteredEvent } from '@classytic/arc/events';
+
+const placed = createEvent('order.placed', { orderId: 'o1' }, {
+  correlationId: req.id, userId: user.id,
+});
+await app.events.publish(placed.type, placed.payload, placed.meta);
+
+// Downstream handler emits a child — correlation inherited, causation linked:
+const reserved = createChildEvent(placed, 'inventory.reserved', { sku: 'a' });
+// reserved.meta.correlationId === placed.meta.correlationId (stays stable across chain)
+// reserved.meta.causationId   === placed.meta.id            (direct parent)
+
+// Transports with native DLQ (Kafka, SQS) implement optional deadLetter():
+class KafkaTransport implements EventTransport {
+  async deadLetter(dlq: DeadLetteredEvent) { /* route to .DLQ topic */ }
+}
+```
+
+`EventMeta` also accepts `schemaVersion` (evolve event payloads) and `partitionKey` (ordered delivery hint for Kafka/Kinesis).
+
 ### defineEvent — Typed Events with Schema Validation
 
 Declare events with schemas for runtime validation and introspection:
@@ -709,7 +739,6 @@ Arc sets `"sideEffects": false` in [package.json](package.json), so modern bundl
 | `@classytic/arc/presets` | Preset functions + interfaces |
 | `@classytic/arc/audit` | Audit trail |
 | `@classytic/arc/idempotency` | Idempotency |
-| `@classytic/arc/policies` | Policy engine |
 | `@classytic/arc/schemas` | TypeBox helpers |
 | `@classytic/arc/utils` | Errors, circuit breaker, state machine, query parser |
 | `@classytic/arc/testing` | Test utilities, mocks, in-memory DB |
@@ -722,46 +751,29 @@ Arc sets `"sideEffects": false` in [package.json](package.json), so modern bundl
 | `@classytic/arc/docs` | OpenAPI generation |
 | `@classytic/arc/cli` | CLI commands (programmatic) |
 
-## v2.8.4 Highlights
+## Type imports
 
-- **MCP ↔ AI SDK bridge** — expose AI SDK `tool()` definitions over MCP without duplicating code. `bridgeToMcp(bridge)` adapts any AI SDK tool into an MCP tool with automatic auth, guard delegation, and `{ error } → isError` envelope translation. `buildMcpToolsFromBridges(bridges, { include, exclude })` registers a whole catalog at once with per-environment filtering.
+Arc owns framework types (`IController`, `IRequestContext`, `ResourceConfig`, `RepositoryLike`, `PaginationResult`). The repository contract lives in `@classytic/repo-core` — import those types directly:
 
 ```typescript
-import { bridgeToMcp, buildMcpToolsFromBridges, type McpBridge } from '@classytic/arc/mcp';
-
-export const triggerJobBridge: McpBridge = {
-  name: 'trigger_job',
-  description: 'Start a job.',
-  inputSchema: { phase: z.enum(['investigate', 'fix']) },
-  annotations: { destructiveHint: true },
-  buildTool: (ctx) => buildTriggerJobTool(getUserId(ctx) ?? ''),
-};
-
-await app.register(mcpPlugin, {
-  resources,
-  extraTools: buildMcpToolsFromBridges([triggerJobBridge]),
-});
+// Arc framework types
+import type { IRequestContext, RepositoryLike, PaginationResult } from '@classytic/arc';
+
+// Repository contract (repo-core is the single source of truth)
+import type { StandardRepo, WriteOptions, QueryOptions } from '@classytic/repo-core/repository';
+import type { OffsetPaginationResult } from '@classytic/repo-core/pagination';
 ```
 
-## v2.8.1 Highlights
+> Arc 2.10 dropped the legacy `CrudRepository`, `PaginatedResult`, and pass-through `WriteOptions`/`QueryOptions` re-exports. See [CHANGELOG.md](CHANGELOG.md#210) for the migration table.
 
-- **Per-action discriminated validation** — `actions` schemas now enforce required fields via a `oneOf` body schema; missing inputs are rejected at the HTTP layer by AJV (no more silent bypass)
-- **Actions in OpenAPI** — `POST /:id/action` endpoint auto-generated from `ResourceDefinition.actions`, with per-action descriptions and the same discriminated body schema as the runtime router
-- **Route/action metadata preserved** — `mcp: false`, `description`, `annotations` no longer dropped during `routes → additionalRoutes` normalization
-- **Canonical source retained** — `ResourceDefinition.routes` and `ResourceDefinition.actions` now kept as declared, so OpenAPI/MCP/registry can read the original shape
-- **Outbox hardening** — expanded `OutboxStore` contract (`claimPending`, `fail`, write options, dedupe, visibleAt), ownership-mismatch throws, onError reporting, safe multi-worker relay
-- **`slugLookup` fallback** — works with MongoKit's default Repository (no custom `getBySlug` needed)
+## v2.10 Highlights
 
-## v2.8.0 Highlights
+- **Clean-break on repo-core types** — `CrudRepository` / `PaginatedResult` / pass-through repo options removed from arc's public surface. Import `StandardRepo`, `OffsetPaginationResult`, etc. directly from `@classytic/repo-core`. See [CHANGELOG.md](CHANGELOG.md) for the rewrite table.
+- **Outbox bugfix** — `repositoryAsOutboxStore.fail()` now passes `updatePipeline: true` to `findOneAndUpdate`, so retry / DLQ transitions work on mongokit ≥3.10.
+- **Plugin requirements documented** — audit / outbox / idempotency require mongokit's `methodRegistryPlugin` + `batchOperationsPlugin` for `deleteMany`; README snippets + production-ops docs now show the correct chain.
+- **Removed** — `@classytic/arc/policies` (use `permissions/`), `@classytic/arc/rpc`, `@classytic/arc/dynamic` (use `factory/loadResources`).
 
-- **MCP Integration** — expose resources as AI agent tools (stateless by default, service scope, multi-tenancy)
-- **Reply Helpers** — `reply.ok()`, `reply.fail()`, `reply.paginated()`, `reply.stream()` (opt-in)
-- **Error Mappers** — class-based `instanceof` domain error → HTTP response mapping
-- **Multipart Body** — `multipartBody()` middleware for file upload in CRUD routes
-- **Service Scope** — `kind: "service"` RequestScope for machine-to-machine auth (MCP + WebSocket)
-- **BigInt Serialization** — `serializeBigInt: true` auto-converts BigInt → Number
-- **Event WAL** — skips internal `arc.*` events to prevent startup timeout with durable stores
-- **Security** — `auth: false` produces null `ctx.user` (prevents anonymous bypass of `!!ctx.user` guards)
+See [CHANGELOG.md](CHANGELOG.md) for the full v2.9 / v2.8 / v2.7 history.
 
 ## License