@classytic/arc 2.41.1 → 2.44.0

package/skills/arc/references/production.md

@@ -76,8 +76,8 @@ Default `0`, which is the pre-2.41 behaviour: close the moment SIGTERM arrives.
 
 `drainDelayMs` is the window between "start failing readiness" and "stop accepting":
 
-- `/health/ready` → `503 { status: 'draining' }` immediately on signal
-- `/health/live` → stays `200` (a draining process is alive — that's the point; a 503 here gets the pod **killed**, not drained)
+- `/_health/ready` → `503 { status: 'draining' }` immediately on signal
+- `/_health/live` → stays `200` (a draining process is alive — that's the point; a 503 here gets the pod **killed**, not drained)
 - everything already routed here is still served for the whole window
 
 Set it **above** your LB's deregistration window — typically 5000–15000ms. On Kubernetes, also keep `terminationGracePeriodSeconds` > `drainDelayMs + timeout`, or the kubelet SIGKILLs you mid-drain.
@@ -299,7 +299,7 @@ const app = await createApp({
       path: '/events/stream',       // SSE endpoint (default: '/events/stream')
       requireAuth: true,            // Fail-closed auth (default: true)
       patterns: ['order.*', 'product.*'],  // Event patterns to stream (default: ['*'])
-      orgScoped: false,             // Filter events by org from request.scope (default: false)
+      // orgScoped defaults to TRUE (2.41.1) — a caller only sees its own org's events.
       heartbeat: 30000,             // Heartbeat interval in ms (default: 30000)
     },
   },
@@ -307,7 +307,7 @@ const app = await createApp({
 
 // Manual registration
 import { ssePlugin } from '@classytic/arc/plugins';
-await fastify.register(ssePlugin, { requireAuth: true, orgScoped: true });
+await fastify.register(ssePlugin, { requireAuth: true });
 ```
 
 ### Realtime resource change feed (2.22)
@@ -322,12 +322,9 @@ row-permissioned resources through it); event firehose → sse. Massive fan-out
 (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
-```
-
 **Fail-closed auth:** When `requireAuth: true` (default), throws at registration if `fastify.authenticate` is missing — prevents exposing SSE without auth.
 
-**Org-scoped:** When `orgScoped: true`, events with `organizationId` are only sent to clients whose `request.scope` matches. Prevents cross-tenant leakage.
+**Org-scoped by default (2.41.1):** an event carrying `organizationId` reaches only callers in that org. It defaulted to `false` — with `patterns: ['*']`, one tenant's member received every tenant's events, full documents included. Events with no `organizationId` still reach everyone, so single-tenant apps are unaffected; an elevated admin with no active org sees all tenants (the platform view). `orgScoped: false` is for a deliberately cross-tenant stream only — keep `requireAuth` and add a `filter`.
 
 ## Error Handler Plugin
 
@@ -383,7 +380,7 @@ return reply.header('content-type', 'text/csv').send(readableStream);
 
 ### BigInt Serialization
 
-Opt-in: `createApp({ serializeBigInt: true })` — auto-converts BigInt → Number in all JSON responses.
+Opt-in: `createApp({ serializeBigInt: 'string' })` — BigInt → decimal string in JSON responses (lossless); `'number'` is lossy above 2^53-1.
 
 ## Multipart Body Middleware (v2.7.3)
 
@@ -678,7 +675,27 @@ await outbox.store(event, { session });
 const relayed = await outbox.relay();  // publishes pending → transport
 ```
 
-**OutboxStore interface**: `save(event)`, `getPending(limit)`, `acknowledge(eventId)` (+ optional `claimPending`, `fail`, `getDeadLettered`, `purge`). When you pass `repository`, arc adapts it internally.
+**Prefer the module form** — it owns the relay schedule, shutdown, and a readiness check, so none of that is hand-wired:
+
+```typescript
+import { createOutboxModule, exponentialBackoff, repositoryAsOutboxStore } from '@classytic/arc/events';
+
+const outbox = createOutboxModule({
+  store: repositoryAsOutboxStore(new Repository(OutboxModel)),
+  // Bounds retries AND log volume. `attempts` is the DURABLE count (it survives relay
+  // restarts and is shared across relays), so a poison event really does stop at 5.
+  failurePolicy: ({ attempts }) =>
+    attempts >= 5 ? { deadLetter: true } : { retryAt: exponentialBackoff({ attempt: attempts }) },
+  health: { relayLagUnhealthyMs: 5 * 60_000, probeCacheMs: 5_000 },
+});
+// createApp({ modules: [outbox] }); consumers declare dependsOn: ['outbox'].
+```
+
+- `requestDrain()` — nudge a pass after commit (milliseconds, not `relayEveryMs`); runs outside the caller's request scope.
+- `drain()` — await delivery, cascades included. For tests and a shutdown that should empty the queue.
+- `health()` + readiness check `<name>.relay` — **non-critical** (a stalled relay is a cluster problem; pulling one pod would not drain it). Unhealthy on any dead letter or pending lag past the threshold. The probe reuses a reading for `probeCacheMs` so N replicas × probe rate do not become N count queries a second on the outbox table.
+
+**OutboxStore contract** (`@classytic/primitives/outbox`): required `save`, `getPending`, `acknowledge`; optional `claimPending` / `claimPendingFenced` (lease + fencing token, and the durable `attempts`), `fail`, `getDeadLettered`, `requeue`, `purge`, `countByStatus`, `oldestPendingAgeMs`. Prove a custom store with `runOutboxStoreContract` from `@classytic/arc/testing/outbox`. When you pass `repository`, arc adapts it internally.
 
 ## Bulk Operations Preset
 

package/dist/actionPermissions-BoPGQ5-4.mjs

@@ -1,350 +0,0 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { n as getUserRoles } from "./userHelpers-ChRvkuSZ.mjs";
-import { b as isElevated, n as PUBLIC_SCOPE, x as isMember } from "./types-CgenB1gv.mjs";
-import { a as resolveEffectiveRoles, t as applyFieldReadPermissions } from "./fields-BHrkoF5y.mjs";
-import { t as buildRequestScopeProjection } from "./projection-BzIgzoKZ.mjs";
-import { t as executePipeline } from "./pipe-FMWNheSO.mjs";
-import { isPaginatedResult, toCanonicalList } from "@classytic/repo-core/pagination";
-//#region src/core/fastifyAdapter.ts
-/** Type guard for Mongoose-like documents with toObject() */
-function isMongooseDoc(obj) {
-	return !!obj && typeof obj === "object" && "toObject" in obj && typeof obj.toObject === "function";
-}
-/**
-* Apply field mask to a single object
-* Filters fields based on include/exclude rules
-*/
-function applyFieldMaskToObject(obj, fieldMask) {
-	if (!obj || typeof obj !== "object") return obj;
-	const plain = isMongooseDoc(obj) ? obj.toObject() : obj;
-	const { include, exclude } = fieldMask;
-	if (include && include.length > 0) {
-		const filtered = {};
-		for (const field of include) if (field in plain) filtered[field] = plain[field];
-		return filtered;
-	}
-	if (exclude && exclude.length > 0) {
-		const filtered = { ...plain };
-		for (const field of exclude) delete filtered[field];
-		return filtered;
-	}
-	return plain;
-}
-/**
-* Apply field mask to response data (handles both objects and arrays)
-*/
-function applyFieldMask(data, fieldMask) {
-	if (!fieldMask) return data;
-	if (Array.isArray(data)) return data.map((item) => applyFieldMaskToObject(item, fieldMask));
-	if (data && typeof data === "object") return applyFieldMaskToObject(data, fieldMask);
-	return data;
-}
-/**
-* Project `FastifyRequest` into the curated `IRequestContext` shape that
-* arc's controllers receive. This is a developer-facing facade, not a
-* portability boundary — arc is Fastify-only. The projection lifts the
-* fields tenant-scoped controllers reach for (`organizationId`,
-* `teamId`, `scope`, `context`, server accessor) onto a flat, typed
-* surface so handler code doesn't have to dig through Fastify's
-* decorator surface or `req.metadata._scope` internals.
-*/
-function createRequestContext(req) {
-	const reqWithExtras = req;
-	const requestContext = reqWithExtras.context ?? {};
-	const srv = req.server;
-	const serverAccessor = {
-		events: srv && "events" in srv ? srv.events : void 0,
-		audit: srv && "audit" in srv ? srv.audit : void 0,
-		queryCache: srv && "queryCache" in srv ? srv.queryCache : void 0,
-		log: req.log
-	};
-	const rawScope = reqWithExtras.scope;
-	const scopeProjection = buildRequestScopeProjection(rawScope);
-	return {
-		query: reqWithExtras.query ?? {},
-		body: reqWithExtras.body ?? {},
-		params: reqWithExtras.params ?? {},
-		headers: reqWithExtras.headers,
-		user: reqWithExtras.user ? (() => {
-			const user = reqWithExtras.user;
-			const rawId = user._id ?? user.id;
-			const normalizedId = rawId ? String(rawId) : void 0;
-			return {
-				...user,
-				id: normalizedId,
-				_id: normalizedId
-			};
-		})() : null,
-		context: requestContext,
-		scope: scopeProjection,
-		metadata: {
-			...reqWithExtras.context,
-			arc: reqWithExtras.arc,
-			_scope: rawScope,
-			_ownershipCheck: reqWithExtras._ownershipCheck,
-			_crossTenantRead: reqWithExtras._crossTenantRead,
-			_policyFilters: reqWithExtras._policyFilters ?? {},
-			log: reqWithExtras.log
-		},
-		server: serverAccessor
-	};
-}
-/**
-* Get typed auth context from an IRequestContext.
-* Use this in controller overrides to access request context.
-*
-* For org scope, use `getControllerScope(req)` instead.
-*/
-function getControllerContext(req) {
-	return req.context ?? req.metadata ?? {};
-}
-/**
-* Get request scope from an IRequestContext.
-* Returns the RequestScope set by auth adapters.
-*/
-function getControllerScope(req) {
-	return req.metadata?._scope ?? PUBLIC_SCOPE;
-}
-/**
-* Compute per-field capability metadata for the current user.
-* Only includes fields that have restrictions — unrestricted fields
-* are omitted (frontend defaults to { readable: true, writable: true }).
-*/
-function computeFieldCapabilities(fieldPerms, effectiveRoles) {
-	const caps = {};
-	for (const [field, perm] of Object.entries(fieldPerms)) {
-		let readable = true;
-		let writable = true;
-		switch (perm._type) {
-			case "hidden":
-				readable = false;
-				writable = false;
-				break;
-			case "visibleTo":
-				readable = perm.roles?.some((r) => effectiveRoles.includes(r)) ?? false;
-				break;
-			case "writableBy": writable = perm.roles?.some((r) => effectiveRoles.includes(r)) ?? false;
-		}
-		caps[field] = {
-			readable,
-			writable
-		};
-	}
-	return caps;
-}
-/**
-* Send a controller's `IControllerResponse` through Fastify's reply.
-*
-* The `IControllerResponse<T>` envelope is arc's internal pipeline
-* contract — it's how custom `status`, `meta`, `headers`, and field
-* permissions thread from a handler through interceptors to the wire
-* without each step having to touch `reply` directly. Not a portability
-* abstraction (arc is Fastify-only); a pipeline-internal one.
-*
-* **Auto-envelope of bare returns.** Custom route handlers are
-* expected to return the envelope shape so this function can apply
-* field permissions, attach `fieldCaps`, and flatten paginated lists.
-* A handler that returns raw `T` (array, plain object, primitive) used
-* to silently produce a broken response — `response.data` was
-* `undefined`, the body sent was `undefined`, and any declared
-* `fields:` permission map was bypassed (the leak shape mentora
-* flagged). 2.17 detects bare returns and wraps them into
-* `{ data: response, status: 200 }` before the field-permission
-* pipeline runs, so `fields:` applies to ALL custom routes whether the
-* handler envelopes its return value or not. The envelope shape is
-* still the canonical contract — auto-wrapping is a safety net, not
-* an invitation to drop the envelope.
-*/
-function sendControllerResponse(reply, response, request) {
-	if (response === null || typeof response !== "object" || !Object.hasOwn(response, "data")) response = {
-		data: response,
-		status: 200
-	};
-	const reqWithExtras = request;
-	const fieldMaskConfig = reqWithExtras?.fieldMask;
-	const arcMeta = reqWithExtras?.arc;
-	const scope = reqWithExtras?.scope ?? PUBLIC_SCOPE;
-	const fieldPerms = isElevated(scope) ? void 0 : arcMeta?.fields;
-	const effectiveRoles = fieldPerms ? resolveEffectiveRoles(getUserRoles(reqWithExtras?.user), isMember(scope) ? scope.orgRoles : []) : [];
-	const fieldCaps = fieldPerms ? computeFieldCapabilities(fieldPerms, effectiveRoles) : void 0;
-	const hasFieldRestrictions = !!(fieldMaskConfig || fieldPerms);
-	/** Apply both field mask and field-level permissions to a data item */
-	const applyPermissions = (data) => {
-		let result = fieldMaskConfig ? applyFieldMask(data, fieldMaskConfig) : data;
-		if (fieldPerms && result && typeof result === "object") {
-			if (Array.isArray(result)) result = result.map((item) => applyFieldReadPermissions(item, fieldPerms, effectiveRoles));
-			else result = applyFieldReadPermissions(result, fieldPerms, effectiveRoles);
-		}
-		return result;
-	};
-	if (response.headers) for (const [key, value] of Object.entries(response.headers)) reply.header(key, value);
-	if (response.data && typeof response.data === "object" && Array.isArray(response.data.data)) {
-		const payload = response.data;
-		const filteredRows = hasFieldRestrictions ? applyPermissions(payload.data) : payload.data;
-		let canonical;
-		if (isPaginatedResult(payload)) canonical = toCanonicalList({
-			...payload,
-			data: filteredRows
-		});
-		else if (typeof payload.page === "number" && typeof payload.limit === "number" && typeof payload.total === "number") canonical = toCanonicalList({
-			method: "offset",
-			data: filteredRows,
-			page: payload.page,
-			limit: payload.limit,
-			total: payload.total,
-			pages: payload.pages ?? Math.ceil(payload.total / Math.max(1, payload.limit)),
-			hasNext: payload.hasNext ?? false,
-			hasPrev: payload.hasPrev ?? false
-		});
-		else canonical = toCanonicalList(filteredRows);
-		reply.code(response.status ?? 200).send({
-			...canonical,
-			...response.meta ?? {},
-			...fieldCaps ? { fieldPermissions: fieldCaps } : {}
-		});
-		return;
-	}
-	const rawData = hasFieldRestrictions ? applyPermissions(response.data) : response.data;
-	const filteredData = rawData !== null && typeof rawData === "object" && typeof rawData.toJSON === "function" ? rawData.toJSON() : rawData;
-	const status = response.status ?? 200;
-	if (filteredData !== null && typeof filteredData === "object" && !Array.isArray(filteredData) && (response.meta || fieldCaps)) {
-		reply.code(status).send({
-			...filteredData,
-			...response.meta ?? {},
-			...fieldCaps ? { fieldPermissions: fieldCaps } : {}
-		});
-		return;
-	}
-	reply.code(status).send(filteredData);
-}
-/**
-* Bridge an `IController` method (`(ctx: IRequestContext) => Promise<IControllerResponse<T>>`)
-* into a Fastify route handler. Translates between arc's curated request
-* context surface and Fastify's request/reply, and routes the envelope
-* through `sendControllerResponse` so the pipeline applies field
-* permissions, status, and meta uniformly. Internal plumbing, not a
-* portability layer — arc is Fastify-only.
-*
-* @example
-* ```typescript
-* const controller = new BaseController(repository);
-* const listHandler = createFastifyHandler(controller.list.bind(controller));
-* fastify.get('/products', listHandler);
-* ```
-*/
-function createFastifyHandler(controllerMethod) {
-	return async (req, reply) => {
-		sendControllerResponse(reply, await controllerMethod(createRequestContext(req)), req);
-		return reply;
-	};
-}
-/**
-* Create Fastify adapters for all CRUD methods of an IController
-*
-* Returns Fastify-compatible handlers for each CRUD operation
-*
-* @example
-* ```typescript
-* const controller = new BaseController(repository);
-* const handlers = createCrudHandlers(controller);
-*
-* fastify.get('/', handlers.list);
-* fastify.get('/:id', handlers.get);
-* fastify.post('/', handlers.create);
-* fastify.patch('/:id', handlers.update);
-* fastify.delete('/:id', handlers.delete);
-* ```
-*/
-function createCrudHandlers(controller) {
-	return {
-		list: createFastifyHandler(controller.list.bind(controller)),
-		get: createFastifyHandler(controller.get.bind(controller)),
-		create: createFastifyHandler(controller.create.bind(controller)),
-		update: createFastifyHandler(controller.update.bind(controller)),
-		delete: createFastifyHandler(controller.delete.bind(controller))
-	};
-}
-//#endregion
-//#region src/core/middlewares/pipeline.ts
-/**
-* Resolve pipeline steps for a specific operation.
-* Flat-array config applies to every op; map config applies per-op.
-*/
-function resolvePipelineSteps(pipeline, operation) {
-	if (!pipeline) return [];
-	if (Array.isArray(pipeline)) return pipeline;
-	return pipeline[operation] ?? [];
-}
-/**
-* Wrap a controller method (one that takes `IRequestContext` and returns
-* `IControllerResponse<T>`) with pipeline execution. Used by CRUD ops and
-* string-handler custom routes.
-*/
-function buildPipelineHandler(controllerMethod, steps, operation, resourceName) {
-	return async (req, reply) => {
-		const pipeCtx = {
-			...createRequestContext(req),
-			resource: resourceName,
-			operation
-		};
-		sendControllerResponse(reply, await executePipeline(steps, pipeCtx, (ctx) => controllerMethod(ctx), operation), req);
-	};
-}
-/**
-* Wrap an action handler (one that takes `(id, data, req)` and returns a raw
-* result) with pipeline execution. Returns a function that produces a full
-* `IControllerResponse<unknown>` — the action router feeds this directly into
-* `sendControllerResponse`, so field masking, custom status codes, `meta`,
-* `details`, and structured error codes from pipeline interceptors flow
-* through to the client unchanged.
-*
-* CRUD and actions now share the same parity invariant: a pipeline that
-* returns `{ success: false, status: 422, error, details, meta }` reaches the
-* client with all four fields intact. Previously the action path stringified
-* failures into a generic `Error` and dropped everything except `statusCode`.
-*
-* Handler throws still bubble out — the caller's try/catch handles `onError`
-* shaping and the generic `ACTION_FAILED` fallback.
-*/
-function buildActionPipelineHandler(handler, steps, operation, resourceName) {
-	if (steps.length === 0) return async (id, data, req) => ({
-		status: 200,
-		data: await handler(id, data, req)
-	});
-	return async (id, data, req) => {
-		const pipeCtx = {
-			...createRequestContext(req),
-			resource: resourceName,
-			operation
-		};
-		return executePipeline(steps, pipeCtx, async (_ctx) => ({
-			status: 200,
-			data: await handler(id, data, req)
-		}), operation);
-	};
-}
-//#endregion
-//#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 { createCrudHandlers as a, getControllerContext as c, resolvePipelineSteps as i, getControllerScope as l, buildActionPipelineHandler as n, createFastifyHandler as o, buildPipelineHandler as r, createRequestContext as s, resolveActionPermission as t, sendControllerResponse as u };