CONTRIBUTING.md

Contributing to OmniGlyph

మీ ఆసక్తికి ధన్యవాదాలు! ఈ ప్రాజెక్ట్‌కు రెండు నాన్-నెగోషియబుల్ కల్చర్ రూల్స్ ఉన్నాయి — README లోని ప్రతి సంఖ్యనూ నమ్మదగినదిగా చేసేది ఇవే.

Rule 1 — Strict TDD

అన్ని ప్రొడక్షన్ కోడ్ ముందుగా ఫెయిల్ అయిన టెస్ట్ నుండి పుడుతుంది:

1. టెస్ట్‌ను రాయండి మరియు అది సరైన కారణంతో ఫెయిల్ అవుతుండటం చూడండి.
2. దాన్ని పాస్ చేయడానికి కనీసం అవసరమైనది రాయండి.
3. గ్రీన్‌గా ఉంటూనే రీఫ్యాక్టర్ చేయండి.

పూర్తి బార్: pnpm run typecheck && pnpm test && pnpm run build — ఎప్పుడూ మూడూ (docs link-lint మరియు rebrand గార్డ్ tests/docs-integrity.test.ts ద్వారా pnpm test లోపలే రన్ అవుతాయి).

Rule 2 — Measurement before claims

జ్యామితి, అట్లాస్, బిల్లింగ్ ఫార్ములా, లేదా మోడల్ స్కోప్‌కు చేసే ఏ మార్పు కూడా కొలవబడిన సంఖ్య లేకుండా ల్యాండ్ కాదు. ఈ రిపోజిటరీ ఈ క్రమశిక్షణ చుట్టూ నిర్మించబడింది:

• బిల్లింగ్ ఖర్చు → దాన్ని benchmarks/billing-sweep/ తో నిరూపించండి (count_tokens ఉచితం; ఆశించిన అవశేషం: సున్నా).
• చదవగలిగే స్థాయి → దాన్ని benchmarks/density-frontier/ తో నిరూపించండి (ఆర్మ్‌కు n≥30, డిటర్మినిస్టిక్ స్కోరింగ్, JSONL రసీదులు benchmarks/*/results/కు కమిట్ చేయబడతాయి).
• ప్రొడక్షన్ డిఫాల్ట్‌ను మార్చడానికి అంగీకార బార్: gist == text baseline మరియు సున్నా నిశ్శబ్ద ఎగ్జాక్ట్-స్ట్రింగ్ ఎర్రర్‌లు మరియు పాజిటివ్ సేవింగ్స్.

సంఖ్యలు లేని పరికల్పనలు docs/ROADMAP.mdకు పరికల్పనలుగానే వెళతాయి — README లోకి వాస్తవాలుగా ఎప్పుడూ కాదు. రెండు "స్పష్టమైన" ఆలోచనలు ఇప్పటికే డేటాతో తిరస్కరించబడ్డాయి (హై-రెస్ పేజీ, యాంటీ-అలయాస్డ్ అట్లాస్); ఈ ప్రక్రియ పనిచేస్తుంది.

Setup

pnpm install
pnpm test              # full suite, ~40–90s
pnpm run dev:node      # local proxy in watch mode

Node ≥18 (CI 20/22/24ను టెస్ట్ చేస్తుంది), pnpm 10 (package.json లోని packageManager ద్వారా పిన్ చేయబడింది).

Structure

ఫోల్డర్	రూల్
src/core/	రన్‌టైమ్-అగ్నోస్టిక్ (Web APIలు మాత్రమే — Node మరియు Workers రెండింటిపైనా నడుస్తుంది)
src/node.ts / src/worker.ts	హోస్ట్ ప్లంబింగ్ మాత్రమే
benchmarks/	మళ్లీ రన్ చేయగలిగే హార్నెస్‌లు; JSONL ఫలితాలు రసీదులు, కమిట్ చేయబడతాయి
docs/	benchmarks/ (సంఖ్యలు), architecture/ (మ్యాప్), ROADMAP (పరికల్పనలు), ops/ (OmniRoute)

Commits and PRs

• కన్వెన్షనల్ కమిట్‌లు (feat:, fix:, perf:, docs:, refactor:, test:, chore:), సంబంధిత సంఖ్యలతో ఎందుకు అని వివరించే బాడీ.
• చిన్న, ఫోకస్డ్ PRలు; బిహేవియర్ మార్పులు వాటిని పిన్ చేసే టెస్ట్‌తో మరియు, వర్తించినప్పుడు, వాటిని సమర్థించే బెంచ్‌మార్క్‌తో వస్తాయి.
• క్లయింట్ యొక్క cache_control బ్లాక్‌లను తిరిగి రాయవద్దు, చర్చ లేకుండా రన్‌టైమ్ డిపెండెన్సీలను జోడించవద్దు (కోర్ ఉద్దేశపూర్వకంగా డిపెండెన్సీ-లైట్‌గా ఉంటుంది), రెండర్ పాత్‌లలో Math.random/టైమ్‌స్టాంప్‌లు వాడవద్దు (డిటర్మినిజం ఒక హార్డ్ ఇన్వేరియంట్, బైట్-ఐడెంటిటీ ద్వారా టెస్ట్ చేయబడుతుంది).