@classytic/arc 2.33.0 → 2.35.0

package/skills/arc/SKILL.md

@@ -69,13 +69,13 @@ 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.34).** `createApp({ role })` declares what a process is FOR, so the same codebase ships as api / worker / relay / scheduler without per-deployment builds:
+**`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.34 behaviour, unchanged. `createWorker()` forwards `role`; without one it still runs everything non-HTTP.
+`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.
 
@@ -321,9 +321,9 @@ Decorates `app.authenticate` / `app.optionalAuthenticate` / `app.authorize`.
 - **`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.34).** 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.34).** 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.34).** 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.
+- **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
 
@@ -489,7 +489,7 @@ defineResource({
 
 POST/PATCH/DELETE bumps resource version. Response header: `x-cache: HIT | STALE | MISS`. `runtime: 'distributed'` requires `stores.queryCache: RedisCacheStore`.
 
-## Transactional writes (2.34)
+## 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:
 
@@ -532,9 +532,9 @@ createApp({ modules: [createOutboxModule({ store: repositoryAsOutboxStore(outbox
 // 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.34):** 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.
+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.34)** — delivery survives crash and deploy, using the outbox machinery rather than a second queue:
+**Durable webhooks (2.33)** — delivery survives crash and deploy, using the outbox machinery rather than a second queue:
 
 ```typescript
 const store = repositoryAsOutboxStore(deliveryRepo);
@@ -727,7 +727,7 @@ 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.34)
+## 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:
 

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

@@ -126,7 +126,7 @@ import {
 import { tracingPlugin } from '@classytic/arc/plugins/tracing';
 import { auditPlugin } from '@classytic/arc/audit';
 import { idempotencyPlugin } from '@classytic/arc/idempotency';
-// Runtime capability registry (2.34) — declare process-local state so a
+// 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';
 ```

package/dist/actionPermissions-CUeCmpUd.mjs

@@ -1,25 +0,0 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-//#region src/core/actionPermissions.ts
-/**
-* Return the effective `PermissionCheck` for a single action, or `undefined`
-* when the resource declares no gate at any level.
-*
-* Callers decide what "no gate" means:
-*   - HTTP: boot-time throw in `normalizeActionsToRouterConfig`.
-*   - MCP: tool-generation throw in `resourceToTools` (mirrors HTTP — the
-*     two surfaces fail closed identically so MCP can't expose an
-*     unauthenticated mutating tool when the HTTP plugin lifecycle hasn't
-*     run).
-*   - OpenAPI: docs advertise the endpoint as unauthenticated.
-*/
-function resolveActionPermission(input) {
-	const { action, resourcePermissions, resourceActionPermissions, globalAuth } = input;
-	const explicit = typeof action !== "function" && action.permissions ? action.permissions : void 0;
-	if (explicit) return explicit;
-	if (resourceActionPermissions) return resourceActionPermissions;
-	if (globalAuth) return globalAuth;
-	const updateFallback = resourcePermissions?.update;
-	if (updateFallback) return updateFallback;
-}
-//#endregion
-export { resolveActionPermission as t };

package/dist/defineAggregation-Nv-DwfOf.mjs

@@ -1,48 +0,0 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-//#region src/core/aggregation/defineAggregation.ts
-/**
-* Declare a single resource aggregation. Exported configs flow into
-* `defineResource({ aggregations: { ... } })` either as named keys or
-* via auto-discovery patterns (loadAggregations — future).
-*
-* @example Inline
-* ```ts
-* defineResource({
-*   name: 'order',
-*   aggregations: {
-*     revenueByStatus: defineAggregation({
-*       groupBy: 'status',
-*       measures: { count: 'count', revenue: 'sum:totalPrice' },
-*       permissions: requireRoles(['admin']),
-*     }),
-*   },
-* });
-* ```
-*
-* @example Multi-file
-* ```ts
-* // orders/aggregations/revenue-by-status.ts
-* import { defineAggregation } from '@classytic/arc';
-*
-* export const revenueByStatus = defineAggregation({
-*   groupBy: 'status',
-*   measures: { count: 'count', revenue: 'sum:totalPrice' },
-*   permissions: requireRoles(['admin']),
-*   timeout: 5000,
-*   cache: { staleTime: 60 },
-* });
-*
-* // orders/order.resource.ts
-* import * as aggregations from './aggregations/index.js';
-*
-* defineResource({
-*   name: 'order',
-*   aggregations,                                  // 30+ entries flow in
-* });
-* ```
-*/
-function defineAggregation(config) {
-	return config;
-}
-//#endregion
-export { defineAggregation as t };

package/dist/preloadResources-BkyqeTDz.mjs

@@ -1,46 +0,0 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-//#region src/factory/preloadResources.ts
-/**
-* Normalize an eager `import.meta.glob` result into a `ResourceLike[]`.
-*
-* Accepts either:
-* - `{ import: 'default' }` form: values are the resource directly
-* - default form: values are the full module — picks first export with `toPlugin()`
-*
-* Throws if any module doesn't yield a valid `ResourceLike`.
-*/
-function preloadResources(globResult) {
-	const resources = [];
-	for (const [path, value] of Object.entries(globResult)) {
-		const resource = pickResource(value);
-		if (!resource) throw new Error(`preloadResources: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
-		resources.push(resource);
-	}
-	return resources.sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
-}
-/**
-* Normalize a lazy `import.meta.glob` result into a `Promise<ResourceLike[]>`.
-*
-* Use this when resources depend on prior bootstrap (e.g., engine init) and
-* cannot be evaluated at import time of the preload file.
-*/
-async function preloadResourcesAsync(globResult) {
-	return (await Promise.all(Object.entries(globResult).map(async ([path, loader]) => {
-		const resource = pickResource(await loader());
-		if (!resource) throw new Error(`preloadResourcesAsync: ${path} does not export a valid resource.\n    Expected: a default export OR a named export with toPlugin().`);
-		return resource;
-	}))).sort((a, b) => (a.name ?? "").localeCompare(b.name ?? ""));
-}
-function pickResource(value) {
-	if (!value || typeof value !== "object") return void 0;
-	if (typeof value.toPlugin === "function") return value;
-	const mod = value;
-	const candidates = [
-		mod.default,
-		mod.resource,
-		...Object.values(mod)
-	];
-	for (const c of candidates) if (c && typeof c === "object" && typeof c.toPlugin === "function") return c;
-}
-//#endregion
-export { preloadResourcesAsync as n, preloadResources as t };

package/dist/registerRoute-DNnd3vkz.mjs

@@ -1,113 +0,0 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-import { n as evaluateAndApplyPermission } from "./authorizationDecision-B3mP_QTy.mjs";
-import { f as createError } from "./errors-Cd_yy7aW.mjs";
-import { u as getRequestScope } from "./types-CoqIRrkY.mjs";
-//#region src/core/middlewares/permissions.ts
-/**
-* Build a PermissionContext from a Fastify request. Extracted so the CRUD
-* permission middleware and the dynamic action-permission check use the same
-* field layout — divergence here silently broke policy filters for actions.
-*/
-function buildPermissionContext(req, opts) {
-	const reqWithExtras = req;
-	const params = req.params;
-	return {
-		user: reqWithExtras.user ?? null,
-		scope: getRequestScope(req),
-		request: req,
-		resource: opts.resource,
-		action: opts.action,
-		resourceId: opts.resourceId ?? params?.id,
-		params,
-		data: opts.data ?? req.body
-	};
-}
-/**
-* Static per-route CRUD permission gate. The permission and action are known
-* at route-registration time, so the gate is a plain preHandler.
-*
-* Actions use the dynamic counterpart `buildActionPermissionMw` — their
-* permission is resolved from `body.action` at request time.
-*/
-function buildCrudPermissionMw(permissionCheck, resourceName, action) {
-	if (!permissionCheck) return null;
-	return async (req, reply) => {
-		const context = buildPermissionContext(req, {
-			resource: resourceName,
-			action
-		});
-		await evaluateAndApplyPermission(permissionCheck, context, req, reply);
-	};
-}
-/**
-* Dynamic per-action permission gate for the action router.
-*
-* Resolves the permission from `body.action` at request time and runs
-* `evaluateAndApplyPermission` from the canonical `permissionMw` slot — so
-* `_policyFilters` and `request.scope` are installed BEFORE `pluginMw`
-* (idempotency) and `routeGuards` run. Previously this check lived inside
-* the main action handler, which meant idempotency recorded unauthorized
-* requests and route guards saw unfiltered scope — the very divergence
-* routerShared exists to prevent.
-*
-* Also acts as a defensive fallback for invalid action names — the
-* `oneOf` body schema normally rejects these at AJV validation, but
-* hosts that disable schema validation still get a 400 here.
-*/
-function buildActionPermissionMw(actionEnum, actionPermissions, globalAuth, resourceName) {
-	const enumSet = new Set(actionEnum);
-	const validActions = [...actionEnum];
-	return async (req, reply) => {
-		const body = req.body ?? {};
-		const action = body.action;
-		if (!action || !enumSet.has(action)) throw createError(400, `Invalid action '${action ?? ""}'. Valid actions: ${validActions.join(", ")}`, { validActions });
-		const permissionCheck = actionPermissions[action] ?? globalAuth;
-		if (!permissionCheck) return;
-		const { action: _discard, ...data } = body;
-		const params = req.params;
-		const context = buildPermissionContext(req, {
-			resource: resourceName,
-			action,
-			resourceId: params?.id,
-			data
-		});
-		await evaluateAndApplyPermission(permissionCheck, context, req, reply, { defaultDenialMessage: (user) => user ? `Permission denied for '${action}'` : "Authentication required" });
-	};
-}
-//#endregion
-//#region src/core/middlewares/registerRoute.ts
-/**
-* Register a route with friendly handling of `FST_ERR_DUPLICATED_ROUTE`.
-*
-* Boot-time `validateRouteCrudCollisions()` catches custom-route → auto-CRUD
-* overlaps before Fastify ever runs, but a few cases still slip through to
-* Fastify itself: two presets contributing the same `routes` entry, hosts
-* mounting two resources at the same prefix, custom routes that share a
-* URL with another plugin. Fastify's default message ("Method 'GET'
-* already declared for route '/'") gives no hint at the resource-shaped
-* fix — `disabledRoutes: ['list']` — so wrap it with one.
-*/
-function tryRegisterRoute(fastify, opts, context) {
-	try {
-		fastify.route(opts);
-	} catch (err) {
-		const fastifyErr = err;
-		if (fastifyErr?.code !== "FST_ERR_DUPLICATED_ROUTE") throw err;
-		const method = opts.method;
-		const url = opts.url;
-		const opHint = context.op ? ` (op: ${context.op})` : "";
-		const fixHint = context.op && [
-			"list",
-			"get",
-			"create",
-			"update",
-			"delete"
-		].includes(context.op) ? ` Suppress the auto-CRUD route with \`disabledRoutes: ['${context.op}']\`.` : " If a custom route in `routes:` collides with auto-CRUD, add `disabledRoutes: ['list' | 'get' | 'create' | 'update' | 'delete']` to `defineResource()` to suppress the matching auto-CRUD route.";
-		const enhanced = /* @__PURE__ */ new Error(`[arc] Duplicate route ${method} ${url} on resource "${context.resourceName}"${opHint}.${fixHint} Original: ${fastifyErr.message ?? "FST_ERR_DUPLICATED_ROUTE"}`);
-		enhanced.code = "FST_ERR_DUPLICATED_ROUTE";
-		enhanced.cause = err;
-		throw enhanced;
-	}
-}
-//#endregion
-export { buildActionPermissionMw as n, buildCrudPermissionMw as r, tryRegisterRoute as t };

package/dist/repositoryFilter-DKny7PDn.mjs

@@ -1,45 +0,0 @@
-/*! @classytic/arc v2.34.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 };

package/dist/simpleEqualityMatcher-Se8VrsaP.mjs

@@ -1,69 +0,0 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-//#region src/utils/simpleEqualityMatcher.ts
-/**
-* `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality
-* matcher for `DataAdapter.matchesFilter` / `BaseController({ matchesFilter })`.
-*
-* **What it does:** for each `[key, expected]` in the filter, compares
-* `item[key]` to `expected` via string coercion (so Mongo `ObjectId` values
-* match their string representation) and returns `true` only if every
-* filter entry matches. Array item values are matched implicitly (contains).
-*
-* **What it does NOT do:**
-* - No `$eq` / `$ne` / `$in` / `$nin` / `$gt` / `$lt` / `$regex` / `$exists`
-* - No `$and` / `$or`
-* - No dot-path traversal (`"owner.id"`)
-* - No schema-specific coercion
-*
-* **Why it exists:** 95%+ of arc's `_policyFilters` are produced by built-in
-* permission helpers and are shaped like `{ ownerId: "u1" }` or
-* `{ organizationId: "org_x" }` — flat equality. For that common shape,
-* this helper is a safe, tested, 15-line defense-in-depth matcher that
-* hosts using minimal repos (no `getOne(compoundFilter)` DB path) can opt
-* into without arc shipping a full Mongo-syntax engine.
-*
-* **When to use:**
-* - Your adapter/repo doesn't natively filter on `getOne(compoundFilter)`
-* - Your `_policyFilters` are flat equality (from arc's built-in permission helpers)
-* - You want defense-in-depth on `validateItemAccess` / `fetchDetailed`'s `getById` fallback
-*
-* **When NOT to use:**
-* - Your `_policyFilters` use operators (`$in`, `$ne`, etc.) — supply a
-*   native matcher (mongokit's repo does the filter at the DB layer; for
-*   custom repos, wrap the kit's own predicate engine).
-* - You're a mongokit / sqlitekit / Prisma user — the DB-level filter
-*   applied by `getOne(compoundFilter)` already covers this.
-*
-* @example
-* ```ts
-* import { simpleEqualityMatcher } from '@classytic/arc/utils';
-*
-* // On a custom adapter
-* const adapter: DataAdapter = {
-*   repository,
-*   type: 'custom',
-*   name: 'in-memory',
-*   matchesFilter: simpleEqualityMatcher,
-* };
-*
-* // Or directly on BaseController for ad-hoc controllers
-* new BaseController(repo, { matchesFilter: simpleEqualityMatcher });
-* ```
-*/
-function simpleEqualityMatcher(item, filters) {
-	if (!item || typeof item !== "object") return false;
-	const obj = item;
-	for (const [key, expected] of Object.entries(filters)) {
-		if (expected && typeof expected === "object" && !Array.isArray(expected) && Object.getPrototypeOf(expected) === Object.prototype && Object.keys(expected).some((k) => k.startsWith("$"))) return false;
-		const actual = obj[key];
-		if (Array.isArray(actual)) {
-			const expectedStr = String(expected);
-			if (!actual.some((v) => String(v) === expectedStr)) return false;
-			continue;
-		}
-		if (String(actual) !== String(expected)) return false;
-	}
-	return true;
-}
-//#endregion
-export { simpleEqualityMatcher as t };