@classytic/arc 2.11.3 → 2.13.1

package/skills/arc-code-review/references/severity.md

@@ -0,0 +1,127 @@
+# Severity Rubric
+
+Score every finding by **blast radius × likelihood of harm × ease of detection in current tests**. Don't grade by code volume — a one-line auth bypass beats 200 lines of duplicated CRUD.
+
+Severity legend: 🔴 Critical · 🟠 High · 🟡 Medium · 🟢 Low
+
+---
+
+## 🔴 Critical — fix this release
+
+A finding is **critical** if it meets any of:
+
+- **Auth/authorization bypass.** `req.user.role` accessed without scope guard on a public route, missing tenant filter, hand-rolled idempotency that double-charges under retry, webhook signature verification on parsed body.
+- **Data leakage.** Manual `toJSON` transform with sensitive fields not declared `hidden`. New sensitive fields (added later) inherit the leak silently.
+- **Drift in security-critical wiring.** Custom controller that doesn't forward `tenantField`, so multi-tenant injection silently fails.
+- **Silent failure modes.** Headers set in `onSend` (intermittent `ERR_HTTP_HEADERS_SENT` under load), `failOpen` events on a path that needs delivery guarantees.
+- **Runtime crashes.** `req.user._id` access on `allowPublic()` routes (crashes only when unauthenticated request hits — usually missed in dev).
+
+**Examples (from anti-patterns.md):** §4, §5, §9, §17, §18, §25, §27, §32.
+
+**Action:** stop the audit, write a hot-fix recommendation, then continue. These can ship as standalone PRs ahead of the broader migration.
+
+---
+
+## 🟠 High — fix this quarter
+
+A finding is **high** if:
+
+- **Duplicated arc behavior** that *will* drift. Five `fastify.get/post/patch/delete` calls per resource where one `defineResource` would do — one resource gets a fix the others don't.
+- **Wrong abstraction layer.** Driver imports (`mongoose`, `@prisma/client`, `drizzle-orm`) leaking into `services/`, `hooks/`, `routes/`. Forces every consumer to pull a database driver; complicates testing.
+- **Missing arc capability** that's already a pain point. Manual idempotency, manual rate-limiting, manual event emission inconsistency, hand-rolled audit trail. The team is building tools arc already provides.
+- **Whole-suite refactor.** No mongokit adoption (§28). Each Mongoose model is a 100+ LOC reduction.
+
+**Examples:** §3, §7, §10, §19, §20, §22, §28.
+
+**Action:** prioritize by occurrence count. A pattern repeated 30 times outranks an isolated high.
+
+---
+
+## 🟡 Medium — fix opportunistically
+
+A finding is **medium** if:
+
+- **Drift surface, not yet harmful.** Manual query parsing where the fields parsed are well-known and stable; manual cache invalidation where the cache strategy works today but breaks on rollout.
+- **Documentation drift.** Hand-maintained OpenAPI/Swagger that's currently in sync but will inevitably diverge.
+- **Preset adoption gap.** Soft-delete/multi-tenant/bulk wired manually instead of via preset. Code works but doesn't benefit from preset upgrades.
+- **Style of contract.** Custom controller without forwarding hooks (works today, breaks when arc updates).
+
+**Examples:** §1, §2, §6, §8, §14, §16, §21, §23, §24, §26.
+
+**Action:** bundle into resource-by-resource refactor PRs. Don't open a separate "fix all medium" PR.
+
+---
+
+## 🟢 Low — fix when adjacent
+
+A finding is **low** if:
+
+- **Code-style only.** `console.log`, `any`, `@ts-ignore`, default exports, tsconfig path aliases breaking auto-discovery.
+- **Cosmetic config.** Missing `displayName` / `module` on `defineResource`, no `arc-cheatsheet` subpath imports, missing `arc docs` script in package.json.
+- **Nicety, not problem.** Manual auth registration instead of `createApp({ auth })` — works fine if app is small.
+
+**Examples:** §11, §12, §13, §29, §30, §31.
+
+**Action:** fix when touching the file for another reason. Don't write a dedicated PR.
+
+---
+
+## Triage examples
+
+### "Found 47 manual permission checks across 12 resources"
+🔴 Critical (auth surface) → list each as a separate finding **only if** the check pattern differs. If they're all `if (!req.user.roles.includes('admin')) throw ...`, group as one finding with 47 occurrences.
+
+### "Found `mongoose` imported in 8 service files"
+🟠 High → architectural. Group by service module, not file, since a service rewrite touches all files in the module together.
+
+### "Found 3 separate `softDelete` reimplementations across resources"
+🟡 Medium → preset adoption. Bundle with the resource refactor.
+
+### "Found `console.log` in 23 places"
+🟢 Low → unless any are inside a hot path with sensitive data (then escalate to High for *those* specific calls).
+
+---
+
+## When to escalate severity
+
+Escalate one tier higher if:
+
+- **The pattern is in a write path.** Any pattern in `POST/PATCH/DELETE` is one tier worse than the same pattern in `GET`.
+- **The pattern is in `auth/`, `webhooks/`, `payments/`, `audit/`, or anything customer-money-touching.** All findings in these paths are at minimum 🟠.
+- **The team has been bitten before.** If `git log` shows a hot-fix commit for a related bug, the underlying pattern is at minimum 🟠.
+- **No tests cover the path.** A medium pattern with no test cover is high — drift will land in prod.
+
+Escalate one tier lower if:
+
+- **The path is feature-flagged off** in production.
+- **The path is admin-only and there are <5 admins** with manually verified scope.
+- **A migration is already in flight** for this pattern (don't double-count).
+
+---
+
+## Reporting cadence
+
+For a single audit:
+
+- **Top 3 criticals** in the executive summary.
+- **All highs** in the body.
+- **Mediums grouped by category** (one row each: "12× manual query parsing").
+- **Lows in an appendix** or omitted.
+
+Don't dump every finding into one giant table — readers will skip. Give them the headline first.
+
+---
+
+## Score → migration estimate
+
+Rough conversion for the executive summary's "estimated effort" line:
+
+| Critical findings | Highs | Mediums | Lows | Effort |
+|---|---|---|---|---|
+| 0 | <5 | <10 | any | S (1–3 days, 1 dev) |
+| 0 | 5–15 | 10–30 | any | M (1–2 weeks, 1 dev) |
+| 1–3 | 5–15 | 10–30 | any | M+ (2 weeks, 2 devs — split critical fixes) |
+| any | >15 | >30 | any | L (1 month+, plan in phases) |
+| >3 | any | any | any | Stop the audit, raise critical fixes first, then re-audit |
+
+These are heuristics. Adjust for codebase size and test coverage.

package/dist/EventTransport-CfVEGaEl.d.mts

@@ -1,293 +0,0 @@
-//#region src/events/EventTransport.d.ts
-/**
- * Event Transport Interface
- *
- * Defines contract for event delivery backends.
- * Implement for durable transports (Redis, RabbitMQ, Kafka, etc.)
- *
- * @example
- * // Redis Pub/Sub implementation
- * class RedisEventTransport implements EventTransport {
- *   async publish(event) {
- *     await redis.publish(event.type, JSON.stringify(event));
- *   }
- *   async subscribe(pattern, handler) {
- *     redis.psubscribe(pattern);
- *     redis.on('pmessage', (p, channel, msg) => handler(JSON.parse(msg)));
- *   }
- * }
- */
-/**
- * Event metadata.
- *
- * Split out as a standalone interface so primitives / downstream packages can
- * mirror it without re-declaring the DomainEvent wrapper. See events.ts in
- * @classytic/primitives for the sibling shape.
- */
-interface EventMeta {
-  /** Unique event ID (UUID v4 recommended) */
-  id: string;
-  /** Event timestamp */
-  timestamp: Date;
-  /**
-   * Schema version for this event type. Default: `1`.
-   *
-   * Use when the payload shape evolves so handlers can branch on version
-   * during migration windows (`if (event.meta.schemaVersion === 2) ...`).
-   * Bump ONLY when the payload contract changes in a breaking way.
-   */
-  schemaVersion?: number;
-  /**
-   * Correlation ID — stays stable across an entire causal chain so a single
-   * user action can be traced through every downstream event. Spans service
-   * boundaries. Generated at the edge (HTTP request, CLI invocation) and
-   * inherited by every child event.
-   */
-  correlationId?: string;
-  /**
-   * Causation ID — the `meta.id` of the direct parent event that caused
-   * this one. Forms a linked-list of cause-and-effect within a correlation.
-   *
-   * Distinct from correlationId: correlation groups, causation chains.
-   * Use {@link createChildEvent} to populate this automatically.
-   */
-  causationId?: string;
-  /**
-   * Partition key hint for ordered transports (Kafka, Kinesis, Redis Streams
-   * consumer groups). Events with the same partitionKey are guaranteed to be
-   * delivered in publish order by transports that honour it.
-   *
-   * Defaults to `resourceId` if unset. Transports that don't support ordering
-   * (in-memory, simple pub/sub) ignore this field.
-   */
-  partitionKey?: string;
-  /** Source resource (e.g. 'order', 'transaction') */
-  resource?: string;
-  /** Resource identifier */
-  resourceId?: string;
-  /** User who triggered the event */
-  userId?: string;
-  /** Organization context */
-  organizationId?: string;
-  /**
-   * Originating service or package (e.g. `'commerce'`, `'billing'`, `'arc-core'`).
-   *
-   * In a multi-service deployment, consumers route / log / alert by `source`
-   * without parsing `type` prefixes. Arc itself never populates this — hosts
-   * set it once per emitter (`app.events.publish('order.placed', p, { source: 'commerce' })`).
-   * Inherited by {@link createChildEvent} so downstream events carry the same
-   * source unless overridden.
-   */
-  source?: string;
-  /**
-   * Idempotency key — stable hint that this event represents a specific
-   * operation exactly once. Consumers dedupe with `if (processed.has(meta.idempotencyKey)) return`.
-   *
-   * Survives every transport (Memory / Pub-Sub / Streams / Kafka) because it's
-   * part of the event, not a transport-side option. Distinct from `meta.id`
-   * (which is fresh per emit — a retry would produce a new id).
-   *
-   * Typical sources: HTTP `Idempotency-Key` header, outbox `dedupeKey`, or
-   * `{aggregate.type}:{aggregate.id}:{action}`. Inherited by child events.
-   */
-  idempotencyKey?: string;
-  /**
-   * DDD aggregate marker — the aggregate that owns this event's invariant.
-   *
-   * Use when routing events by aggregate, doing event-sourcing replay, or
-   * enforcing consistency boundaries. Distinct from `resource` / `resourceId`
-   * (HTTP-origin entity) because an event emitted *by* one REST resource can
-   * *belong to* a different aggregate (e.g. `POST /orders/:id/ship` emits
-   * `shipment.dispatched` owned by a shipment aggregate).
-   *
-   * Downstream packages narrow `aggregate.type` to their own string union via
-   * interface extension:
-   *
-   * ```ts
-   * type CartAggregateType = 'cart' | 'cart-item';
-   * interface CartEventMeta extends EventMeta {
-   *   aggregate?: { type: CartAggregateType; id: string };
-   * }
-   * ```
-   *
-   * Not inherited by {@link createChildEvent} — child events typically belong
-   * to a different aggregate than their parent.
-   */
-  aggregate?: {
-    type: string;
-    id: string;
-  };
-}
-interface DomainEvent<T = unknown> {
-  /** Event type (e.g., 'product.created', 'order.shipped') */
-  type: string;
-  /** Event payload */
-  payload: T;
-  /** Event metadata */
-  meta: EventMeta;
-}
-type EventHandler<T = unknown> = (event: DomainEvent<T>) => void | Promise<void>;
-/**
- * A permanently-failed event routed to a dead-letter sink after retries
- * have been exhausted. Mirrors the shape a caller would log, alert on, or
- * replay from once the upstream issue is fixed.
- */
-interface DeadLetteredEvent<T = unknown> {
-  /** The original event */
-  event: DomainEvent<T>;
-  /** Serialised failure reason (message + optional machine code + stack) */
-  error: {
-    message: string;
-    code?: string;
-    stack?: string;
-  };
-  /** How many delivery attempts were made before giving up */
-  attempts: number;
-  /** First failure timestamp */
-  firstFailedAt: Date;
-  /** Last failure timestamp (immediately before dead-lettering) */
-  lastFailedAt: Date;
-  /** Optional handler / subscriber name that last failed (for debug) */
-  handlerName?: string;
-}
-/**
- * Minimal logger interface for event transports.
- * Compatible with `console`, `pino`, `fastify.log`, and any custom logger.
- *
- * @example
- * ```typescript
- * // Use Fastify's logger
- * new MemoryEventTransport({ logger: fastify.log });
- *
- * // Use a custom logger
- * new MemoryEventTransport({ logger: { warn: myWarn, error: myError } });
- *
- * // Default: console (no logger option needed)
- * new MemoryEventTransport();
- * ```
- */
-interface EventLogger {
-  warn(message: string, ...args: unknown[]): void;
-  error(message: string, ...args: unknown[]): void;
-}
-interface EventTransport {
-  /** Transport name for logging */
-  readonly name: string;
-  /**
-   * Publish an event to the transport
-   */
-  publish(event: DomainEvent): Promise<void>;
-  /**
-   * Publish a batch of events to the transport (optional, v2.8.1+).
-   *
-   * Transports that can efficiently batch (Kafka producer, Redis pipeline,
-   * RabbitMQ publisher confirms, SQS send-message-batch) should implement
-   * this. {@link import('./outbox.js').EventOutbox.relay} auto-detects and
-   * uses it for much higher throughput than per-event publishing.
-   *
-   * **Contract**: the returned `PublishManyResult` must describe the
-   * per-event outcome so the caller can acknowledge successes and fail the
-   * rest. Partial success is allowed — the transport reports it per event.
-   *
-   * If not implemented, `EventOutbox.relay` falls back to calling
-   * {@link publish} once per event.
-   *
-   * @param events - Events to publish (in order)
-   * @returns Per-event outcome map keyed by `event.meta.id`
-   */
-  publishMany?(events: readonly DomainEvent[]): Promise<PublishManyResult>;
-  /**
-   * Subscribe to events matching a pattern
-   * @param pattern - Event type pattern (e.g., 'product.*', '*')
-   * @param handler - Handler function
-   * @returns Unsubscribe function
-   */
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  /**
-   * Route a permanently-failed event to the transport's dead-letter sink
-   * (Kafka DLQ topic, SQS DLQ, Redis Stream `PEL` timeout handler, etc.).
-   *
-   * Called by {@link import('./outbox.js').EventOutbox} after exhausting
-   * retries. Transports that don't have a native DLQ can omit this —
-   * callers treat an absent `deadLetter` as "log and drop".
-   */
-  deadLetter?(dlq: DeadLetteredEvent): Promise<void>;
-  /**
-   * Close transport connections
-   */
-  close?(): Promise<void>;
-}
-/**
- * Per-event outcome returned by {@link EventTransport.publishMany}.
- *
- * The key is `event.meta.id`; the value is `null` for success or an `Error`
- * for per-event failure. Transports MUST include an entry for every event
- * in the input batch.
- */
-type PublishManyResult = ReadonlyMap<string, Error | null>;
-interface MemoryEventTransportOptions {
-  /** Logger for error/warning messages (default: console) */
-  logger?: EventLogger;
-}
-/**
- * In-memory event transport (default)
- * Events are delivered synchronously within the process.
- * Not suitable for multi-instance deployments.
- */
-declare class MemoryEventTransport implements EventTransport {
-  readonly name = "memory";
-  private handlers;
-  private logger;
-  constructor(options?: MemoryEventTransportOptions);
-  publish(event: DomainEvent): Promise<void>;
-  /**
-   * Reference `publishMany` implementation — delegates to `publish()` in order.
-   *
-   * Production transports (Kafka, Redis pipeline, SQS batch) should override
-   * this with a single batched network call. Memory transport has nothing to
-   * batch, so we just loop — the loop still returns a proper result map so
-   * `EventOutbox.relay` can exercise the batched code path in tests.
-   */
-  publishMany(events: readonly DomainEvent[]): Promise<PublishManyResult>;
-  subscribe(pattern: string, handler: EventHandler): Promise<() => void>;
-  close(): Promise<void>;
-}
-/**
- * Create a domain event with auto-generated metadata.
- *
- * `id` and `timestamp` are filled in; everything else is caller-controlled.
- * Set `schemaVersion` explicitly for any event type you plan to evolve.
- */
-declare function createEvent<T>(type: string, payload: T, meta?: Partial<EventMeta>): DomainEvent<T>;
-/**
- * Create a child event that chains causation from a parent event.
- *
- * Rules:
- *  - `causationId` is set to the parent's `id` (direct cause)
- *  - `correlationId` is inherited from the parent if set, else falls back
- *    to the parent's `id` (root correlation)
- *  - `userId` / `organizationId` are inherited when not overridden so the
- *    whole chain stays scoped to the originating principal/tenant
- *
- * Caller-supplied `meta` wins over inherited fields — pass `{ userId: newActor }`
- * to override when a subsystem acts on behalf of a different principal.
- *
- * @example
- * ```typescript
- * const orderPlaced = createEvent('order.placed', { orderId: 'o1' }, {
- *   correlationId: req.id, userId: user.id,
- * });
- * await events.publish(orderPlaced);
- *
- * // Downstream handler emits a child event:
- * const reserved = createChildEvent(orderPlaced, 'inventory.reserved', {
- *   orderId: 'o1', skus: ['sku-1', 'sku-2'],
- * });
- * // reserved.meta.causationId   === orderPlaced.meta.id
- * // reserved.meta.correlationId === orderPlaced.meta.correlationId
- * // reserved.meta.userId        === user.id   (inherited)
- * ```
- */
-declare function createChildEvent<T>(parent: DomainEvent, type: string, payload: T, meta?: Partial<EventMeta>): DomainEvent<T>;
-//#endregion
-export { EventMeta as a, MemoryEventTransportOptions as c, createEvent as d, EventLogger as i, PublishManyResult as l, DomainEvent as n, EventTransport as o, EventHandler as r, MemoryEventTransport as s, DeadLetteredEvent as t, createChildEvent as u };

package/dist/adapters/index.d.mts

@@ -1,3 +0,0 @@
-import { An as RelationMetadata, En as AdapterFactory, Mn as SchemaMetadata, Nn as ValidationResult, On as DataAdapter, jn as RepositoryLike, kn as FieldMetadata } from "../index-6u4_Gg6G.mjs";
-import { a as PrismaQueryParserOptions, c as MongooseAdapterOptions, d as DrizzleAdapterOptions, f as createDrizzleAdapter, i as PrismaQueryParser, l as createMongooseAdapter, n as PrismaAdapterOptions, o as createPrismaAdapter, r as PrismaQueryOptions, s as MongooseAdapter, t as PrismaAdapter, u as DrizzleAdapter } from "../index-BbMrcvGp.mjs";
-export { AdapterFactory, DataAdapter, DrizzleAdapter, DrizzleAdapterOptions, FieldMetadata, MongooseAdapter, MongooseAdapterOptions, PrismaAdapter, PrismaAdapterOptions, PrismaQueryOptions, PrismaQueryParser, PrismaQueryParserOptions, RelationMetadata, RepositoryLike, SchemaMetadata, ValidationResult, createDrizzleAdapter, createMongooseAdapter, createPrismaAdapter };

package/dist/adapters/index.mjs

@@ -1,2 +0,0 @@
-import { a as createMongooseAdapter, i as MongooseAdapter, n as PrismaQueryParser, o as DrizzleAdapter, r as createPrismaAdapter, s as createDrizzleAdapter, t as PrismaAdapter } from "../adapters-D0tT2Tyo.mjs";
-export { DrizzleAdapter, MongooseAdapter, PrismaAdapter, PrismaQueryParser, createDrizzleAdapter, createMongooseAdapter, createPrismaAdapter };