# Package constants — `@suaveplan/rules`

## Purpose

This module exposes the package-level constants consumed across the rules engine, validators, action executor, and event bus. Constants are deliberately separated from feature code so that one canonical source defines the conservative defaults — depth limits, history capacities, timeout deadlines — for the entire package. Every default is overridable through the options object on the relevant constructor or factory function; the defaults exist for the "I just want it to work" call path, not as a behavioural contract.

`PACKAGE_NAME` and `VERSION` are surfaced for diagnostics (error wire format, OTel resource attributes, telemetry headers). They are `const` literals so that downstream tree-shaking can fold them into the bundle as inline strings.

## Features

- `PACKAGE_NAME` — the canonical `@suaveplan/rules` identifier; matches the `name` field in `package.json`.
- `VERSION` — synced to `package.json`'s `version` field at publish time.
- `DEFAULT_MAX_DEPTH` — the recursion depth at which the engine throws `RULES.ENGINE_DEPTH_EXCEEDED`. Set conservatively to 32; well above any realistic business-rule tree, but low enough to detect cyclic or pathological inputs quickly.
- `DEFAULT_EVENT_HISTORY` — the size of the bounded ring buffer maintained by `EventBus`. At 1000 entries the bus keeps recent context for debugging without growing without bound under sustained emission.
- `DEFAULT_ACTION_TIMEOUT_MS` — the default per-action timeout used by `ActionExecutor` when the caller does not supply one. 30s matches the convention used by `@suaveplan/retry` for "long-running but bounded" operations.
- `DEFAULT_ACTION_PARALLELISM` — the concurrency cap applied by `ActionExecutor.executeParallel` when the caller does not supply one. 8 is the sweet spot for IO-bound handlers without saturating an event loop.

## Usage: Basic Example

```ts
import { DEFAULT_MAX_DEPTH, PACKAGE_NAME, VERSION } from "@suaveplan/rules";

console.log(`${PACKAGE_NAME}@${VERSION}, max-depth=${DEFAULT_MAX_DEPTH}`);
```

## Usage: Advanced Example

```ts
import { RuleEngine } from "@suaveplan/rules/engine";
import { DEFAULT_MAX_DEPTH } from "@suaveplan/rules";

// Halve the default depth limit for a constrained edge function.
const engine = new RuleEngine({ maxDepth: DEFAULT_MAX_DEPTH / 2 });
```

## API Reference

| Export | Type | Description |
|---|---|---|
| `PACKAGE_NAME` | `"@suaveplan/rules"` (literal `const`) | Package identifier. |
| `VERSION` | `"0.1.0"` (literal `const`) | Current package version; bumped to `1.0.0` at graduation. |
| `DEFAULT_MAX_DEPTH` | `number` | Engine recursion ceiling. |
| `DEFAULT_EVENT_HISTORY` | `number` | EventBus ring-buffer capacity. |
| `DEFAULT_ACTION_TIMEOUT_MS` | `number` | Per-action timeout in milliseconds. |
| `DEFAULT_ACTION_PARALLELISM` | `number` | Maximum concurrent actions in `executeParallel`. |

## Implementation Notes

- The constants file ships zero runtime initialisation and zero `import`s of other workspace packages. It is intentionally side-effect free so that tree-shakers can prune it cleanly when unused.
- Numbers are declared with `_` digit separators (`30_000`) for readability. The TypeScript target is ES2022, where numeric separators are supported by every published runtime.
- Changes to default values are behaviour changes per AGENTS.md §13a and require a `## Migration` note in the OpenSpec proposal.