@classytic/arc 2.32.0 → 2.34.0

package/skills/arc/SKILL.md

@@ -69,6 +69,14 @@ await app.listen({ port: 8040, host: '0.0.0.0' });
 
 **Boot order (fixed):** `beforeBoot` → modules resolve → `plugins` → `bootstrap[]` → `resources` → `afterResources` → `onReady`.
 
+**`role` — one image, N deployments (2.33).** `createApp({ role })` declares what a process is FOR, so the same codebase ships as api / worker / relay / scheduler without per-deployment builds:
+
+```typescript
+createApp({ role: process.env.ARC_ROLE as 'api' | 'worker' | 'relay' | 'scheduler' | 'all' })
+```
+
+`api` and `worker` mount NO module schedule arms; `relay` mounts only `kind: 'relay'` arms (the outbox relay, durable webhook delivery); `scheduler` mounts all of them. Declaring `relay`/`scheduler` together with `resources`/`resourceDir` is BOOT-FATAL — a relay process must not serve routes. Default `all` is the pre-2.33 behaviour, unchanged. `createWorker()` forwards `role`; without one it still runs everything non-HTTP.
+
 `beforeBoot()` (2.21) runs before Fastify exists and before module thunks / resource files import — connect the DB there instead of dynamic-import ordering hacks.
 
 For async-booted engines, pass `resources` as a factory so it runs after `bootstrap[]`:
@@ -162,7 +170,7 @@ defineResource({ name: 'health', customRoutesOnly: true, routes: [...] });
 defineResource({ name: 'pipeline', adapter, defaultLimit: 200, maxLimit: 500 });
 ```
 
-400s on `?limit=` violations include the cap: `message: "Query parameter 'limit' must be <= 500 (got 800) (cap is 500)"` + `meta: { field: 'limit', cap: 500 }`.
+A `?limit=` above the cap is **clamped to it**, not rejected (2.33 — see Query parsing). The effective cap rides in the OpenAPI parameter description.
 
 ## fieldRules
 
@@ -304,12 +312,18 @@ Decorates `app.authenticate` / `app.optionalAuthenticate` / `app.authorize`.
 ## Authoritative gotchas
 
 - **Field-write reject (default).** Requests carrying non-writable fields → 403 with denied list. Opt into silent strip: `defineResource({ onFieldWriteDenied: 'strip' })`.
+- **Immutable writes are STRIPPED, not refused (default).** `PATCH {"type":"rent"}` on an `immutable` field returns 200 with the value unchanged. Opt into 403: `defineResource({ onImmutableWrite: 'reject' })`, or `ARC_STRICT_IMMUTABLE_WRITES=true`. Separate from `onFieldWriteDenied` because a full-object PATCH echoing an immutable field back UNCHANGED is legitimate, and the sanitizer has no stored document to tell that from a real change — turn it on if you send partial patches.
+- **Log redaction is REPLACED, not merged.** Setting `logger.redact` makes yours the whole policy; arc's defaults stop applying. Superset them: `import { DEFAULT_LOGGER_REDACT_PATHS } from '@classytic/arc/factory'` and spread it into your list, rather than hand-copying (a copy drifts — one host's had lost `*.passwordHash`).
+- **Error disclosure derives from `preset`, falling back to the environment.** `includeStack` and `exposeInternalMessages` are both derived, and host keys MERGE over them — stating one no longer resets the other. Direct `errorHandlerPlugin` registration skips the preset derivation entirely.
 - **multiTenant injects org on UPDATE.** Body `organizationId` is overwritten with caller's scope (closes tenant-hop).
 - **`request.user`** is `Record<string, unknown> | undefined`. Guard with `if (req.user)` on public routes.
 - **Arc reads singular `user.role`** (string, comma-separated, or array). Don't put a plural `roles` field on the model.
 - **`verifySignature(body, …)`** throws on parsed body — pass `req.rawBody`.
 - **MCP tools fail-closed.** A resource action without per-action perm + no `actionPermissions` + no `permissions.update` fallback → throws at tool generation. Declare `allowPublic()` to opt into unauthenticated.
 - **Better Auth roles.** BA stores `member.role = "admin,recruiter"` (comma-separated). Arc splits into `scope.orgRoles = ['admin', 'recruiter']`; `?role=admin` won't match — use `role[like]=admin`.
+- **Read-only repositories refuse write ROUTES at boot (2.33).** Kits' Better Auth overlays are sealed by default (`capabilities.readOnly`) — BA owns hashing, session revocation, org cascades. Mounting `create`/`update`/`delete` over one is boot-fatal: disable those routes, or pass the kit's `unsafeWritable: true` for administrative repair only. Normal identity mutations go through `auth.api`.
+- **Arc closes only stores/transports it BUILT (2.33).** One you hand to `idempotencyPlugin` / `eventPlugin` / `queryCachePlugin` stays yours to close — arc used to close every one, which wiped a co-resident app's live idempotency records.
+- **Idempotency self-checks its store at boot (2.33).** A probe write must read back under its own key and NOT under another; registration throws otherwise. Catches a filter-stripping repository (a pathless Mongoose schema under `strictQuery: true` strips filters to `{}`), which otherwise replays cached responses across keys AND users. `selfCheck: false` to disable; the adapter's per-read identity checks remain.
 
 ## routeGuards + defineGuard
 
@@ -369,6 +383,28 @@ defineResource({
 });
 ```
 
+**An unknown filter key is DROPPED by default, and dropping WIDENS.** `?filters[status]=pending`
+against a parser that does not whitelist `status` returns 200 with every row unfiltered — the
+caller asked to narrow and got a broader set. Refuse instead:
+
+```typescript
+new QueryParser({ allowedFilterFields: [...], strictFilterFields: true })  // 400 ValidationError
+```
+
+Off by default (an unconditional throw would reject requests that work today). Fleet-wide via
+`ARC_STRICT_QUERY_PARAMS=true`; an explicit `false` beats the env. Only the FILTER whitelist —
+a dropped sort or operator degrades ordering, it does not widen the row set.
+
+**`?limit` above the cap CLAMPS, it does not 400** (2.33). The parser and `QueryResolver` both
+clamp, and the querystring schema no longer emits `maximum` — it used to reject first, making the
+documented clamp unreachable and turning a benign over-ask into a 400 that callers render as an
+empty list. The cap is in the parameter description instead, so OpenAPI still shows it.
+
+**One cap, one owner.** Page size is capped by the parser, the repository's pagination engine and
+arc — lowest wins silently. Arc defers to the parser's `maxLimit` when the host states none, and
+WARNS at boot when the parser allows more than the repository (`pagination-cap-mismatch`).
+Configure both to the same number.
+
 ## Aggregations
 
 `GET /:prefix/aggregations/:name` per entry. Portable `$match → $group → $project → $sort → $limit` against `repo.aggregate(req, options)` — same shape across kits.
@@ -453,6 +489,31 @@ defineResource({
 
 POST/PATCH/DELETE bumps resource version. Response header: `x-cache: HIT | STALE | MISS`. `runtime: 'distributed'` requires `stores.queryCache: RedisCacheStore`.
 
+## Transactional writes (2.33)
+
+`transactional: true` runs the PERSISTENCE step inside `withTransaction`. Write verbs receive the tx-bound repository plus `ctx.uow` — the join point for work outside the repository:
+
+```typescript
+defineResource({
+  name: 'order',
+  adapter,
+  transactional: true,
+  writes: {
+    create: async (data, ctx) => {
+      const order = await ctx.repository.create(data);          // tx-bound
+      await outbox.store(event, { session: ctx.uow?.session });  // SAME transaction
+      return order;
+    },
+  },
+});
+```
+
+- Hooks stay OUTSIDE the retry — before/after run once; only persistence re-runs.
+- Transient conflicts re-run with jittered backoff; `VersionConflictError` surfaces (409), never retried.
+- **Retry authority is the KIT's.** mongokit declares `transactionRetry: 'managed'` (its driver already retries internally) and is called exactly once; sqlitekit declares `'caller'` and gets the envelope's loop. Arc never stacks a second policy.
+- **BOOT-FATAL** without `withTransaction`, and at REGISTRATION when the repository reports `capabilities.transactions !== true` (standalone Mongo, D1, unconfirmed topology). The capability is checked at registration, not at `defineResource()`, because that usually runs at module import — before `beforeBoot()` connects.
+- `ctx.uow.session` is empty on connection-bound backends (SQLite); the tx-bound repo is the join point there.
+
 ## Events
 
 CRUD events auto-emit: `{resource}.created` / `{resource}.updated` / `{resource}.deleted`. Manual publish:
@@ -464,13 +525,27 @@ await app.events.subscribe('order.*', async (event) => { … });
 
 Transports: Memory · Redis Pub/Sub (fire-and-forget) · Redis Streams (durable, consumer groups, DLQ). Event types live in `@classytic/primitives/events` (`createEvent`, `createChildEvent`, `matchEventPattern`, …); arc re-exports the runtime `MemoryEventTransport` only.
 
-**Outbox** (at-least-once via transactional outbox):
+**Outbox** (at-least-once via transactional outbox) — prefer the MODULE, so the store is a slot other modules depend on rather than a value threaded by hand:
+
+```typescript
+createApp({ modules: [createOutboxModule({ store: repositoryAsOutboxStore(outboxRepo) })] });
+// Dev: createOutboxModule({ store: new MemoryOutboxStore() })
+```
+
+The relay arm is `kind: 'relay'`, so `role: 'relay'` deployments drain it. It resolves the RAW transport, never the `fastify.events` facade (the facade fails open, which would acknowledge rows whose publish failed) — no transport is boot-fatal. **Fencing (2.33):** stores that support `claimPendingFenced` mint a token in the claim CAS; a relay that lost its lease mid-batch cannot ack or re-schedule a row a successor already owns. Feature-detected end to end.
+
+**Durable webhooks (2.33)** — delivery survives crash and deploy, using the outbox machinery rather than a second queue:
 
 ```typescript
-const outbox = new EventOutbox({ repository: outboxRepo, transport });
-// Dev: { store: new MemoryOutboxStore(), transport }
+const store = repositoryAsOutboxStore(deliveryRepo);
+createApp({
+  modules: [createDurableWebhookModule({ store })],       // relay does the signed POST
+  plugins: async (f) => f.register(webhookPlugin, { durable: { store } }), // enqueue, don't POST
+});
 ```
 
+One row per (event × subscription), deterministic id so an at-least-once upstream enqueues each delivery exactly once. Transient failures (network/timeout/429/5xx) retry with backoff; 4xx dead-letters on the FIRST attempt. `durable` + `retry` together is a registration error.
+
 Full event recipes (retry, DLQ, dual-publish warnings, idempotency keys) → [references/events.md](references/events.md).
 
 ## Hooks
@@ -652,6 +727,23 @@ await app.audit.custom('order', req.params.id, 'refund', { reason }, { user });
 
 `@classytic/arc/usage` — `usagePlugin` decorates `fastify.usage` with per-actor, per-UTC-month counters (`record`/`summary`/`period`/`actorOf`; actor chain org → user → client → ip). Auto-tracks `api.requests` (default on) + `api.egress.bytes` (opt-in); recording is fail-safe (a throwing `UsageStore` never fails a request; `MemoryUsageStore` built in, Redis/kit backends are ~5 lines). Pair with `createApp({ rateLimit: { plan: { resolve, limits: { free: { max: 60 }, enterprise: false }, default: 'free' } } })` for per-plan ceilings — `false` = unlimited, unknown/throwing resolvers fall back to `default` then global `max`, and buckets follow the tenant key chain by default. Caveat: the limiter runs before route auth, so `resolve` sees the raw request.
 
+## Runtime capability registry (2.33)
+
+Under `runtime: 'distributed'`, subsystems holding process-local state must declare it — the end-of-boot audit FAILS the app on undeclared memory state, naming every violator:
+
+```typescript
+import { declareRuntimeCapability } from '@classytic/arc/utils';
+
+declareRuntimeCapability(fastify, {
+  subsystem: 'billing.sequence-cache',
+  durability: 'memory',        // 'memory' | 'shared'
+  accepted: true,              // per-process BY DESIGN (logged, never fatal)
+  detail: 'short-TTL cache; correctness from TTL, not shared state',
+});
+```
+
+`createApp`'s constructor-time guard only sees what it is passed; state a host wires inside `plugins()` was invisible to it and lived on a checklist. This makes the checklist enforcement. Arc's webhooks plugin declares its default in-memory store.
+
 ## Adapters
 
 Cross-framework adapter contract lives in `@classytic/repo-core/adapter`. Every kit-specific adapter ships from its kit's `/adapter` subpath; arc itself has zero kit-bound adapters.

package/skills/arc/references/api-reference.md

@@ -126,8 +126,27 @@ import {
 import { tracingPlugin } from '@classytic/arc/plugins/tracing';
 import { auditPlugin } from '@classytic/arc/audit';
 import { idempotencyPlugin } from '@classytic/arc/idempotency';
+// Runtime capability registry (2.33) — declare process-local state so a
+// `runtime: 'distributed'` boot fails on undeclared memory state:
+import { declareRuntimeCapability } from '@classytic/arc/utils';
 ```
 
+**Idempotency store — the one schema mistake that matters.** Backing the store
+with a repository requires the key path to survive the filter. A Mongoose
+schema with NO declared paths under a global `strictQuery: true` has EVERY
+filter key stripped, so `getOne({ _id: key })` becomes `getOne({})`: one row
+absorbs every key and responses replay across keys AND users. Declare the path
+and pin the option on the schema:
+
+```typescript
+new Schema({ _id: String }, { strict: false, strictQuery: false, timestamps: false })
+// NOT `new Schema({}, { _id: false, strict: false })`
+```
+
+The plugin's boot self-check (default on, `selfCheck: false` to disable) probes
+for exactly this and refuses to register; the adapter also throws
+`IdempotencyStoreMisconfiguredError` on any cross-key read at runtime.
+
 ## Integrations
 
 ```typescript

package/skills/arc/references/production.md

@@ -292,7 +292,7 @@ field masking. Client = plain `EventSource` with `?token=`. No replay — reconn
 refetches the list. Choosing: per-user resource views → realtime; bidirectional/geo
 → `integrations/websocket` (its CRUD bridge is org-coarse — never expose
 row-permissioned resources through it); event firehose → sse. Massive fan-out
-(viral feeds, live scores) → publish once to an edge layer (Ably/Centrifugo/CF)
+(viral feeds, live scores) → publish once to a dedicated edge fan-out layer
 via `app.events.subscribe(...)`; full tiering guide: docs/production-ops/realtime.mdx.
 
 ```typescript
@@ -618,7 +618,7 @@ presets: [bulkPreset({ operations: ['createMany', 'updateMany'], maxCreateItems:
 ## Compensating Transaction
 
 In-process rollback primitive — runs steps in order, compensates in reverse on failure.
-For distributed sagas across services, use Temporal, Inngest, or Streamline.
+For distributed sagas across services, use `@classytic/streamline` or a dedicated workflow orchestrator.
 
 ```typescript
 import { withCompensation } from '@classytic/arc/utils';

package/dist/projection-CjHhM5W1.mjs

@@ -1,18 +0,0 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { c as getOrgId, g as getUserId, x as isMember } from "./types-DXYX7dIR.mjs";
-//#region src/scope/projection.ts
-/**
-* Compute the request-scope projection. Returns `undefined` when no
-* scope is attached (public / unscoped routes) so hosts can idiomatically
-* write `ctx.scope?.organizationId` without a double-null check.
-*/
-function buildRequestScopeProjection(scope) {
-	if (!scope) return void 0;
-	return {
-		organizationId: getOrgId(scope),
-		userId: getUserId(scope),
-		orgRoles: isMember(scope) ? scope.orgRoles : void 0
-	};
-}
-//#endregion
-export { buildRequestScopeProjection as t };

package/dist/repositoryFilter-DotlxG3L.mjs

@@ -1,45 +0,0 @@
-/*! @classytic/arc v2.32.0 | MIT | https://classytic.com */
-import { arcLog } from "./logger/index.mjs";
-import { policyRecordToFilter } from "@classytic/repo-core/filter";
-//#region src/core/repositoryFilter.ts
-const log = arcLog("repository-filter");
-let warnedUnconvertible = false;
-/** True for a `{ $op: ... }` operator object (all keys `$`-prefixed). */
-function isOperatorObject(value) {
-	if (value === null || typeof value !== "object") return false;
-	if (Array.isArray(value) || value instanceof Date) return false;
-	const keys = Object.keys(value);
-	return keys.length > 0 && keys.some((k) => k.startsWith("$"));
-}
-/**
-* Does this compound filter contain any `$`-operator (top-level logical like
-* `$and`/`$or`, or a field operator object like `{ $in: [...] }`)? If not, it is
-* pure flat equality and portable as-is.
-*/
-function filterHasDollarOperator(record) {
-	for (const [key, value] of Object.entries(record)) {
-		if (key.startsWith("$")) return true;
-		if (isOperatorObject(value)) return true;
-	}
-	return false;
-}
-/**
-* Normalize a compound query/policy filter for the repository layer. Flat
-* equality records pass through unchanged; anything carrying `$`-operators is
-* converted to the portable repo-core {@link Filter} IR so it compiles
-* identically on Mongo, SQLite, Postgres, and custom adapters.
-*/
-function toRepositoryFilter(record) {
-	if (!filterHasDollarOperator(record)) return record;
-	try {
-		return policyRecordToFilter(record);
-	} catch (err) {
-		if (!warnedUnconvertible) {
-			warnedUnconvertible = true;
-			log.warn(`A \`\$\`-operator filter could not be normalized to portable Filter IR (operator outside arc's policy dialect). Passing the raw record to the repository — MongoKit handles it; non-Mongo kits may not. (${err instanceof Error ? err.message : String(err)})`);
-		}
-		return record;
-	}
-}
-//#endregion
-export { toRepositoryFilter as t };