platform-db Package Skill

Package: @epicdm/platform-db Repository: flowstate-platform Path: packages/shared/platform-db Version: 0.1.0

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

Platform DB Billing Credits

Status: Active Purpose: Preserve billing credit math and D1 query contracts. Scope: packages/shared/platform-db/src/credit-math.ts, src/schema-billing.ts, and src/queries/billing.ts Trigger: Credit conversion, rate lookup, top-up, usage aggregation, or notification work. Input: Event type, amount in cents or credits, timestamp, tenant ID, and query requirements. Output: Correct credit math and tested billing query behavior.

Workflow

1. Use usdcToCredits(amountCents) for cent-to-credit conversion; it rejects negative amounts.
2. Use creditsToUsdc(credits) when converting back to cents; it floors fractional cents.
3. Use lookupRate(rates, eventType, timestamp) to select the active rate with the latest effectiveFrom.
4. Use prorateStorage(bytes, intervalMs, creditsPerMbMonth, monthMs) for storage intervals.
5. For persisted billing behavior, update src/schema-billing.ts and src/queries/billing.ts together.
6. Verify with the billing test files, not only generic schema tests.

Contracts

Verification

• Run yarn workspace @epicdm/platform-db test -- credit-math.
• Run yarn workspace @epicdm/platform-db test -- billing.
• Run full yarn workspace @epicdm/platform-db test before handing off schema changes.

Package Skill Inventory

Skill Inventory: @epicdm/platform-db

Package Role

@epicdm/platform-db centralizes FlowState platform D1 schema, typed Drizzle access, validation schemas, ID prefixes, query helpers, and billing credit math.

Skills

Composition Notes

• Compose with worker skills that use platform D1 data.
• Use package queries before duplicating SQL in workers.
• Keep Drizzle schema, migrations, tests, and exported query namespaces aligned.

Review Gate

Review Gate: @epicdm/platform-db Skills

Result

Pass.

Checks

• Skills are source-backed by schema, query, validation, ID, credit math, and tests.
• Inventory separates broad schema/query work from billing credit workflows.
• Verification commands are package-local.

Residual Risk

Schema changes can require Drizzle migrations and downstream worker updates. These skills call out the alignment requirement but do not replace migration review.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/shared/platform-db/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.