# grindbaby Contract Specification v1.0.0
**Domain**: Precision Herb Grinder Intelligence, Evaluation & Acquisition Operating System
**Status**: Active / Governed
**Version**: 1.0.0

---

## 1. Domain Overview & Purpose
grindbaby replaces superficial affiliate listicles with a deterministic, laboratory-benchmarked operating system for evaluating, comparing, matching, and acquiring ultra-premium herb grinders. It models the physical mechanics, material science (6061-T6 aluminum vs. 304/316 medical-grade stainless steel vs. ball-bearing mechanisms), particle consistency curves, and device pairings (ball vapes, portable convection, conduction).

---

## 2. Operational Lifecycle
The domain strictly executes across 6 sequential, deterministic stages:

```
[1. Ingestion & Specs] 
       │
       ▼
[2. Milling Benchmark] 
       │
       ▼
[3. Match & Pairing Engine] 
       │
       ▼
[4. Discount & Acquisition Gate] 
       │
       ▼
[5. Exception Handling & Maintenance] 
       │
       ▼
[6. Governance & Audit]
```

### Stage Descriptions:
1. **Ingestion & Spec Extraction**: Ingest grinder metadata: manufacturer, tooth/milling architecture, material grade, closure type (threaded vs. threadless magnetic), diameter, weight, and baseline price tiers.
2. **Milling Benchmark Validation**: Quantitative rating of particle distribution (ultra-fine, medium-fluffy, coarse), torque effort (Nm), jam resistance, and kief separation efficiency.
3. **Match & Vaporizer Pairing**: Deterministic logic matching chamber requirements (e.g., Storz & Bickel Mighty+, TinyMight 2, Flowerpot B1 ball vape, Dynavap) to grind consistency and thread ergonomics.
4. **Discount & Acquisition Gate**: Verified coupon validation (e.g. `420VZ10`, `VAPEZONE`, `TROYTIME`), discount percentage calculation, and routing to authorized vendor URLs.
5. **Exception Handling & Maintenance Protocol**: Recovery workflows for thread binding, resin buildup, bearing lubrication, and material safety alerts.
6. **Governance & Audit**: Affiliation disclosure transparency, metal dust wear verification, and deterministic seed case audit logs.

---

## 3. Data Contracts & Type Boundaries

### 3.1 Grinder Specification Schema (`IGrinder`)

```typescript
export type MaterialGrade = 
  | '6061-T6_ALUMINUM'
  | '304_STAINLESS_STEEL'
  | '316_SURGICAL_STEEL'
  | 'ANODIZED_ALUMINUM';

export type ClosureMechanism = 
  | 'THREADED_QUAD'
  | 'THREADLESS_MAGNETIC'
  | 'BALL_BEARING_AXIAL'
  | 'EXTRUDER_ROTOR';

export type GrindConsistencyProfile = 
  | 'ULTRA_FLUFFY_CONVECTION'
  | 'BALANCED_HYBRID'
  | 'COARSE_BALL_VAPE'
  | 'FINE_CONDUCTION';

export interface IDiscountRule {
  readonly code: string;
  readonly percentage: number;
  readonly flatDiscountUsd?: number;
  readonly verifiedActive: boolean;
  readonly conditionsDescription: string;
}

export interface IGrinder {
  readonly id: string;
  readonly name: string;
  readonly manufacturer: string;
  readonly basePriceUsd: number;
  readonly priceDisplay: string;
  readonly headlineAward: string;
  readonly whyLoved: string;
  readonly material: MaterialGrade;
  readonly closure: ClosureMechanism;
  readonly consistencyProfile: GrindConsistencyProfile;
  readonly diameterMm: number;
  readonly weightGrams: number;
  readonly pieces: number;
  readonly toothType: 'PATENTED_CONCAVE' | 'TOOTHLESS_SCREEN' | 'DIAMOND_CURVED' | 'ROTARY_MILL';
  readonly labScores: {
    readonly fluffiness: number;      // 0-100
    readonly jamResistance: number;    // 0-100
    readonly cleaningEase: number;     // 0-100
    readonly ergonomics: number;       // 0-100
    readonly buildDurability: number;  // 0-100
  };
  readonly affiliateUrl: string;
  readonly discountRule?: IDiscountRule;
  readonly recommendedVapes: readonly string[];
}
```

---

## 4. Deterministic Seed Cases

To guarantee ground truth over synthetic claims, the system executes two explicit seed cases:

### Seed Case A: Happy-Path Standard
- **Subject**: Brilliant Cut Grinder (BCG) — Stainless Steel / Matte Aluminum
- **Lifecycle Evaluation**:
  - *Stage 1*: Extracted as threadless magnetic, 3-piece modular design.
  - *Stage 2*: Fluffiness benchmark score 98/100, jam resistance score 100/100.
  - *Stage 3*: Paired with TinyMight 2 and Storz & Bickel Venty.
  - *Stage 4*: Base price $88, active affiliate link verified.
  - *Stage 5*: Maintenance rating "Near Zero" — requires no ISO soak for months due to non-threading geometry.
  - *Stage 6*: Certified passing in the audit ledger.

### Seed Case B: Exception & Human-Review Gate
- **Subject**: Flower Mill 2.5 Stainless Steel
- **Lifecycle Evaluation**:
  - *Stage 1*: Extracted as rotor-washer toothless milling system.
  - *Stage 2*: High fluffiness score (95/100), low torque required.
  - *Stage 3*: Paired with Volcano Hybrid & Dynavap M+.
  - *Stage 4*: Base price $95, coupon `VAPEZONE` yields 10% savings ($85.50 net).
  - *Stage 5*: **EXCEPTION TRIGGERED**: Rotor washer clearance and food-grade stainless wear requires mandatory pre-flight user verification checklist before milling dense cured material.
  - *Stage 6*: Status: `FLAGGED_HUMAN_GATE` — system requires explicit safety acknowledgment before affiliate redirect.

---

## 5. Non-Negotiable System Invariants

1. **Zero Horizontal Scrolls**: Layout containers must not exceed viewport width at any breakpoint (320px to 4K). Overflow-x must strictly remain `hidden` or `clip`, with text and data grids reflowing gracefully.
2. **Transparent Commercial Disclosures**: Every external link accompanied by verifiable discount calculation math and FTC affiliate disclosures.
3. **No Fabricated Data**: Unconnected inventory feeds or warehouse APIs are declared `UNCONFIGURED` rather than simulated.