docs: author grounded CHARTER.md + CHITTY.md for ChittyScore #3
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,115 @@ | ||
| --- | ||
| 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 | ||
| --- | ||
|
|
||
| # 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/<entity_id>` | GET | Recent scoring history (newest first, limit 20). Requires `DATABASE_URL`; 503 if unset | | ||
| | `/api/trust/demo/<persona_id>` | 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* |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,99 @@ | ||
| --- | ||
| 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 | ||
| --- | ||
|
|
||
| # 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. | ||
|
There was a problem hiding this comment.
This fallback is only true for unknown DID/chitty_id strings. When Useful? React with 👍 / 👎. |
||
|
|
||
| ## 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/<entity_id>` | GET | Yes | Recent scoring history (limit 20); 503 if no `DATABASE_URL` | | ||
|
Comment on lines
+82
to
+83
There was a problem hiding this comment.
In the root Flask service I inspected, Useful? React with 👍 / 👎. |
||
| | `/api/trust/demo/<persona_id>` | 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) | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The root Python implementation I inspected has
SourceDimension.calculate()scoring onlyentity.identity_verifiedand credentials supplied in the request model, and repo-wide search outside docs does not show any ChittyTrust client/config/API call feeding certificate data into that dimension. Presenting this as an active ChittyTrust certificate-data dependency will lead operators and agents to expect certificate-driven Source scoring that the service cannot currently perform, so this should be worded as planned/aspirational or backed by the missing integration.Useful? React with 👍 / 👎.