@forgrit/contracts

Cross-domain Zod schemas + TypeScript types for the ForGrit Foundry OS. The shared vocabulary that every other @forgrit/* package speaks.

Status: early-access (v0.x). Pre-1.0 releases may include breaking changes in minor bumps until the API stabilizes at v1.0.0.

Single runtime dep: zod. Zero NestJS, Prisma, or framework coupling. Pure TypeScript types + Zod schemas. Node 20+.

What's in the box

5 sub-module surfaces:

types/ — TypeScript interfaces

Cross-domain interfaces that span the ForGrit Foundry OS:

• Release lifecycle: ReleaseArtifact, DeploymentEnvironment, DeploymentVersion const enums
• Blueprint: BlueprintContract, ArchitectureBlueprint, IntegrationOptions
• Prompt + planning: PagePlan, PromptContract-related types
• Truth reconciler: TruthReconcilerTruth, drift digest DTOs
• Storage metering: StorageMeterSubcategory, StorageMeterTruth, snapshot DTOs
• Asset transfer: AssetTransfer types
• Support tickets: category vocabulary + DTOs
• Design DNA + variants: DesignDna, archetype-related types
• Figma: entity + conversion types
• Preview: archetype types
• Plus: JobLifecycle, TechDefaults, TechTarget, SSO, app blueprint fragments, etc.

schemas/ — Zod runtime schemas

Zod schemas inferred from the corresponding types/ interfaces. Use these at runtime boundaries (HTTP request parsing, queue payload validation, etc.).

pricing/storage-pricing — Pricing constants + helpers

• STORAGE_PRICING_INR_PER_GB_DAY — per-subcategory rates
• computeStorageCharge(bytes, days, subcategory) — BigInt-safe charge math
• dateBucketUtc(date) — UTC YYYY-MM-DD bucketing for idempotent metering

validators/tech-target.validator

Tech-stack-target validation rules for blueprint planning.

utils/blueprint-accessors

Convenience accessors for navigating blueprint trees.

Install

npm install @forgrit/contracts
# or
pnpm add @forgrit/contracts
# or
yarn add @forgrit/contracts

Quick start

import {
  STORAGE_METER_SUBCATEGORIES,
  computeStorageCharge,
  dateBucketUtc,
} from '@forgrit/contracts';

// Compute a charge for a storage observation
const charge = computeStorageCharge(
  1024n * 1024n * 1024n, // 1 GB in bytes
  1, // 1 day
  STORAGE_METER_SUBCATEGORIES.ARTIFACT,
);
console.log('Charge (INR):', charge); // 0.01

// Date bucket for idempotency
console.log(dateBucketUtc(new Date('2026-05-26T03:00:00Z'))); // '2026-05-26'

What it's NOT

• Not a runtime engine. Pure type definitions + Zod schemas + a handful of pricing helpers.
• Not opinionated about transport. Use the schemas at any boundary (REST, GraphQL, queue, etc.).
• Not coupled to a database. Types describe shapes; persistence is consumer's choice.

Versioning

0.1.x is early-access. The public API may evolve before 1.0.0 locks semver.

License

MIT — see LICENSE.

Links

• npm: https://www.npmjs.com/package/@forgrit/contracts
• Source: https://github.com/forgrit-ai/forgrit/tree/main/packages/contracts
• Issues: https://github.com/forgrit-ai/forgrit/issues
• ForGrit: https://forgrit.ai

Sibling packages (use these together)

• @forgrit/blueprint — app-spec format + blueprint helpers
• @forgrit/llm-cost — credit ledger primitives + 7 LLM cost design rules
• @forgrit/design-engine — recipe + theme combinatorial design engine
• @forgrit/design-intelligence — embedding + RAG + hybrid scoring for design-engine