skills/plugins/document-navigator/docs/foundation/flow/rules/src/constants.md

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

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

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

Usage: Advanced Example

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 imports 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.