diff --git a/CHARTER.md b/CHARTER.md index 52c6b3b..9a6db13 100644 --- a/CHARTER.md +++ b/CHARTER.md @@ -1,5 +1,115 @@ -# Service Charter -> **Canonical URI:** `chittycanon://core/services/canon` -> **Status:** ACTIVE +--- +uri: chittycanon://docs/ops/policy/chittyscore-charter +namespace: chittycanon://docs/ops +type: policy +version: 1.0.0 +status: DRAFT +registered_with: chittycanon://core/services/canon +title: "ChittyScore Charter" +certifier: chittycanon://core/services/chittycertify +visibility: PUBLIC +--- -This service is governed by the ChittyOS Compliance standard. +# ChittyScore Charter + +## Classification +- **Canonical URI**: `chittycanon://core/services/chittyscore` +- **Tier**: 4 (Domain) +- **Organization**: CHITTYFOUNDATION +- **Domain**: score.chitty.cc + +## Mission + +ChittyScore is the **behavioral trust scoring engine** for the ChittyOS ecosystem. It converts an entity's activity — events, credentials, connections, and outcomes — into quantified trust across six weighted dimensions, producing four output scores and a composite ChittyScore. It is the *analytical* counterpart to ChittyTrust's *cryptographic* root authority: ChittyScore measures behavior, ChittyTrust governs cryptographic trust anchors. The two are complementary, never overlapping (see `CHITTYTRUST_ROOT_CA_ARCHITECTURE.md`). + +## Scope + +### IS Responsible For +- 6-dimension behavioral trust calculation (Source, Temporal, Channel, Outcome, Network, Justice) +- Weighted composite scoring and the four output scores (People, Legal, State, ChittyScore) +- Trust-level mapping to the ChittyID lifecycle (L0_ANONYMOUS → L4_INSTITUTIONAL) +- Insight and pattern generation over entity event history +- Confidence estimation based on data quality (event volume, verification, credentials) +- Persistence of results and events to the `chittyscore` Postgres schema (FK to `public.identities`) +- Scoring history retrieval for a resolved identity + +### IS NOT Responsible For +- Identity generation or minting (ChittyID) +- Cryptographic root authority, CA key material, certificate issuance (ChittyTrust / ChittyCert) +- Authentication tokens (ChittyAuth) +- Identity verification documents (ChittyVerify) +- Service registration (ChittyRegister) +- The `public.trust_scores` table (owned by ChittyTrust — DRL / TY-VY-RY governance model) + +## Dependencies + +| Type | Service | Purpose | +|------|---------|---------| +| Upstream | ChittyID | Entity identifiers being scored (`public.identities`, matched by DID or chitty_id) | +| Upstream | ChittyTrust | Consumes certificate/trust-anchor data for the Source dimension | +| Upstream | ChittyAuth | Authentication for API access | +| Downstream | ChittyRegister | Uses trust levels during onboarding decisions | +| Downstream | ChittyCases | Displays trust profiles in case management | +| Downstream | ChittyPortal | Surfaces trust scores in user dashboards | + +## API Contract + +**Base URL**: https://score.chitty.cc + +### Core Endpoints +| Endpoint | Method | Purpose | +|----------|--------|---------| +| `/` | GET | Service info and endpoint index | +| `/api/health` | GET | Service health (`{status, service, timestamp}`) | +| `/api/trust/calculate` | POST | Calculate trust score (body: `{entity: TrustEntity, events: TrustEvent[]}`). Persists to `chittyscore.results` when `entity.id` resolves to an `identities` row and `DATABASE_URL` is set | +| `/api/trust/history/` | GET | Recent scoring history (newest first, limit 20). Requires `DATABASE_URL`; 503 if unset | +| `/api/trust/demo/` | GET | In-memory demo personas (`alice`, `bob`, `charlie`) — never persisted | + +### Scoring Model +Six weighted dimensions (weights sum to 100%): + +| Dimension | Weight | Measures | +|-----------|--------|----------| +| Source | 15% | Identity verification, credentials | +| Temporal | 10% | Account age, consistency, recency | +| Channel | 15% | Channel reliability (verified_api, blockchain, email, …) | +| Outcome | 20% | Positive/negative outcome ratio with recency weighting | +| Network | 15% | Connection quality, endorsements | +| Justice | 25% | Community impact, transparency, dispute resolution | + +Output scores: People (outcome 40 / network 35 / source 25), Legal (justice 50 / outcome 30 / temporal 20), State (source 40 / justice 35 / temporal 25), ChittyScore (full weighted composite). Trust levels: L0 (0+) → L1 (25+) → L2 (50+) → L3 (75+) → L4 (90+). + +## Ownership + +| Role | Owner | +|------|-------| +| Service Owner | ChittyFoundation | +| Technical Lead | @chittyos-infrastructure | +| Security Contact | security@chitty.foundation | + +## Compliance + +- [ ] Service registered in ChittyRegistry +- [x] Health endpoint operational at `/api/health` +- [ ] OpenAPI specification published +- [x] CLAUDE.md development guide present +- [ ] Audit logging to ChittyChronicle active +- [x] Trust level policies aligned to ChittyID lifecycle (L0–L4) + +## Document Triad + +This charter is part of a synchronized documentation triad. Changes to shared fields must propagate. + +| Field | Canonical Source | Also In | +|-------|-----------------|---------| +| Canonical URI | CHARTER.md (Classification) | CHITTY.md (blockquote) | +| Tier | CHARTER.md (Classification) | CHITTY.md (blockquote), CLAUDE.md (Ecosystem Position) | +| Domain | CHARTER.md (Classification) | CHITTY.md (blockquote), CLAUDE.md (Ecosystem Position) | +| Endpoints | CHARTER.md (API Contract) | CHITTY.md (Endpoints table), CLAUDE.md (API Endpoints) | +| Dependencies | CHARTER.md (Dependencies) | CHITTY.md (Dependencies table), CLAUDE.md (Ecosystem Position) | +| Certification badge | CHITTY.md (Certification) | CHARTER.md frontmatter `status` | + +**Related docs**: [CHITTY.md](CHITTY.md) (badge/one-pager) | [CLAUDE.md](CLAUDE.md) (developer guide) + +--- +*Charter Version: 1.0.0 | Last Updated: 2026-06-28* diff --git a/CHITTY.md b/CHITTY.md index c3ff4cc..6724399 100644 --- a/CHITTY.md +++ b/CHITTY.md @@ -1,5 +1,99 @@ -# CHITTY (Agentic Operating Contract) -> **Sovereignty Level:** Dependent -> **Required Identity:** `chitty_id` +--- +uri: chittycanon://docs/ops/architecture/chittyscore +namespace: chittycanon://docs/ops +type: architecture +version: 1.0.0 +status: DRAFT +registered_with: chittycanon://core/services/canon +title: "ChittyScore" +certifier: chittycanon://core/services/chittycertify +visibility: PUBLIC +--- -This file dictates how other ChittyOS autonomous agents interact with this service. +# ChittyScore + +> `chittycanon://core/services/chittyscore` | Tier 4 (Domain) | score.chitty.cc + +## What It Does + +Behavioral trust scoring engine for the ChittyOS ecosystem. Given an entity and its event history, it computes a 6-dimension trust profile, a weighted composite ChittyScore, four output scores (People, Legal, State, ChittyScore), a trust level mapped to the ChittyID lifecycle, and supporting insights with a confidence estimate. + +ChittyScore is **analytical** (behavioral scoring). ChittyTrust is **governance** (cryptographic root authority / CA). They are complementary, not overlapping — ChittyScore consumes ChittyTrust certificate data for its Source dimension but never issues certificates or holds key material. The boundary is documented in `CHITTYTRUST_ROOT_CA_ARCHITECTURE.md`. + +## Architecture + +Python/Flask application. The root project (`app.py` + `src/chitty_score/`) is the canonical 6D scoring engine; the repository also carries independent TypeScript sub-projects (chittyfinance, chittyassets, chittypm, chitty-frontend) with their own stacks. + +### Stack +- **Runtime**: Python 3.11+, Flask 3.0 (Flask-CORS), gunicorn +- **Models/Validation**: Pydantic 2.x +- **Math**: numpy (dimension calculators) +- **Storage**: PostgreSQL via `psycopg2` (Neon, `chittyscore` schema) — optional +- **Container**: Docker (port 5000) + +### Key Components +- `app.py` — Flask app, routes, `TrustEngine` class, dimension weights, demo personas +- `main.py` — entry point, imports and runs `app` +- `src/chitty_score/models.py` — Pydantic models: `TrustEntity`, `TrustEvent`, `Credential`, `Connection` +- `src/chitty_score/dimensions.py` — six async dimension calculators +- `src/chitty_score/analytics.py` — `TrustAnalytics`, insight/pattern generation +- `src/chitty_score/persistence.py` — Postgres persistence layer (`chittyscore.results` / `chittyscore.events`) +- `schema.sql` — Postgres schema (FK to `public.identities`) + +### Scoring Pipeline +``` +TrustEntity + TrustEvent[] + → TrustEngine.calculate_trust() + → 6 weighted dimensions (Source 15 / Temporal 10 / Channel 15 / Outcome 20 / Network 15 / Justice 25) + → weighted composite + → 4 output scores (People, Legal, State, ChittyScore) + → trust level (L0→L4) + insights + confidence +``` + +Persistence is optional: with `DATABASE_URL` set, a result persists only when `entity.id` resolves to a `public.identities` row (by DID or chitty_id); otherwise calculation still succeeds with `persisted: null` and no orphan rows are written. + +## ChittyOS Ecosystem + +### Certification +- **Badge**: ChittyOS Compatible +- **Certifier**: ChittyCertify (`chittycanon://core/services/chittycertify`) +- **Last Certified**: — + +### ChittyDNA +- **ChittyID**: — +- **DNA Hash**: — +- **Lineage**: ChittyTrust (consumes cert data) + ChittyID (consumes identities) + +### Dependencies +| Service | Purpose | +|---------|---------| +| ChittyID | Entity identifiers being scored (`public.identities`) | +| ChittyTrust | Certificate / trust-anchor data for the Source dimension | +| ChittyAuth | Authentication for API access | +| ChittyRegister | Downstream: trust levels for onboarding | +| ChittyCases | Downstream: trust profiles in case management | +| ChittyPortal | Downstream: trust scores in user dashboards | + +### Endpoints +| Path | Method | Auth | Purpose | +|------|--------|------|---------| +| `/` | GET | No | Service info | +| `/api/health` | GET | No | Health check | +| `/api/trust/calculate` | POST | Yes | Calculate trust score (persists when identity resolves) | +| `/api/trust/history/` | GET | Yes | Recent scoring history (limit 20); 503 if no `DATABASE_URL` | +| `/api/trust/demo/` | GET | No | In-memory demo personas (`alice`/`bob`/`charlie`) | + +## Document Triad + +This badge is part of a synchronized documentation triad. Changes to shared fields must propagate. + +| Field | Canonical Source | Also In | +|-------|-----------------|---------| +| Canonical URI | CHARTER.md (Classification) | CHITTY.md (blockquote) | +| Tier | CHARTER.md (Classification) | CHITTY.md (blockquote), CLAUDE.md (Ecosystem Position) | +| Domain | CHARTER.md (Classification) | CHITTY.md (blockquote), CLAUDE.md (Ecosystem Position) | +| Endpoints | CHARTER.md (API Contract) | CHITTY.md (Endpoints table), CLAUDE.md (API Endpoints) | +| Dependencies | CHARTER.md (Dependencies) | CHITTY.md (Dependencies table), CLAUDE.md (Ecosystem Position) | +| Certification badge | CHITTY.md (Certification) | CHARTER.md frontmatter `status` | + +**Related docs**: [CHARTER.md](CHARTER.md) (charter/policy) | [CLAUDE.md](CLAUDE.md) (developer guide)