Imported from crbnos/carbon (packages/utils/AGENTS.md). Install upstream with npx skills add crbnos/carbon --skill utils. Copyright stays with the author.

@carbon/utils

Pure utility functions shared across all Carbon packages and apps. Covers accounting, arrays, BOM, dates, numeric precision and formatting, math, strings, status helpers, the storage/sales rule engine, URL manipulation, and more.

Always

• Import utilities from @carbon/utils — never duplicate utility logic in app code.
• Use sanitize(obj) to strip empty values before Supabase insert/update operations.
• Use domain-specific helpers where they exist: formatCurrency() for money, getStatus() for status resolution, getBomLevel() for BOM traversal.
• Keep utilities pure — no side effects, no database calls, no env access (except isBrowser check). Only @internationalized/date, zod, and lodash.template (plus nanoid and @supabase/supabase-js for the typed supabase.ts wrappers) are allowed runtime deps.

Ask First

• Adding new dependencies — this package is imported everywhere; new deps increase bundle size across all apps.
• Modifying rules.ts / field-registry.ts / rules-schema.ts — the rule-evaluation engine (condition AST compiler, operators, field registry) and its zod mirror. The Operator union is shared with @carbon/workflows; the evaluator gates real inventory transactions and sales-document lines. Used by storage rules (~/modules/inventory) and sales rules (~/modules/sales) across ERP and MES.
• Changing Edition enum or isBrowser detection — used by @carbon/env and auth logic.

Never

• Import server-only packages (@carbon/auth, @carbon/database, @carbon/kv) from here — @carbon/utils must remain client-safe. Deliberate edge-shared utilities: precision.ts, accounting-currency.ts, accounting-posting.ts, payment-funding.ts, sales-posting-amounts.ts, batch-time-split.ts, and batch-compatibility.ts each re-export their namesake under packages/database/supabase/functions/shared/ by relative path (math.ts consumes precision.ts). Those implementations live there because the Supabase edge runtime only mounts supabase/functions/; re-exporting rather than duplicating keeps ONE source of truth so the Node and Deno sides never drift. They are client-safe source imports, not imports of the server/database package, and not something to "fix" (same pattern as packages/database/src/sampling.ts). Keep their dependency graphs pure.
• Add async/IO operations — utilities should be synchronous pure functions (the one exception is supabase.ts helpers which are typed wrappers). File/image handling lives in @carbon/files, not here.
• Duplicate what already exists — check the barrel export (src/index.ts) before adding a new utility.

Validation Commands

pnpm --filter @carbon/utils test        # Runs rule-engine tests etc.
pnpm --filter @carbon/utils typecheck

Key Modules

Numeric precision

Every price, rate, quantity and amount follows the standard in .claude/rules/numeric-precision.md: internal values at SCALE = 5, settlement values at the currency's decimalPlaces (the DB column, authoritative over Intl/CLDR), rounding only at persist / display / compare. Three checks in @carbon/checks enforce it (no-raw-rounding, no-inline-fraction-digits, no-derived-percent-column) and they scan this package.

Cross-References

• packages/env/ — imports Edition and isBrowser from this package
• packages/database/ — service functions use sanitize() from here
• apps/erp/, apps/mes/ — primary consumers of all utility functions