HiveGrid-Wireframes/hivegrid-cloud/docs/agent-playbooks/foundation-boundaries.md

Foundation Boundary Playbook

Use this when moving feature logic into the reusable boilerplate layer or when touching audit, idempotency, flags, permissions, billing usage, or notifications.

Ownership Rules

• Runtime apps may orchestrate requests, headers, sessions, and responses.
• Shared business rules belong in packages/*, preferably @toolctrl/foundation for pure policy and @toolctrl/db for schema-backed server boundaries.
• UI and route modules must not reach around package boundaries for tenant-scoped persistence.
• Foundation exports must stay generic. Do not add product-specific roles, flags, templates, adapters, or catalog entries.

Required Checks

• Audit writes use @toolctrl/db/audit-events.server.
• Idempotency keys use @toolctrl/db/idempotency-keys.server or the API idempotency store bridge.
• API usage limits use @toolctrl/db/usage.server; API routes should not recompute subscription feature math locally.
• Notification deliveries use sourceKey whenever a producer can derive a stable event key, so DB upsert prevents duplicate delivery records.
• Feature flags resolve in this order: explicit override, user scope, tenant scope, global scope, default.

Done Criteria

• Add or update focused tests in the owning package.
• Update feature manifests when a feature changes ownership, billing, provider, worker, or admin-managed behavior.
• Run pnpm run test:foundation, the affected package tests, and the app-level route tests for changed runtimes.