Architecture
How Krypton is put together
Krypton has a local half that reads your code and a scoring half that only receives its structure. This page covers both, the format between them, and what each side can see.
A local halfReads and parses your code, keeps the names.
A scoring halfReceives only structure, stores nothing.
HTTPS betweenStructure and hashes out, numbers and hints back.
Overview
A file is parsed into a syntax tree on your machine, and only that is scored. Where the scorer needs a name it gets a short fingerprint, and the real name stays in a local book. The scorer returns numbers and hints, and your machine puts the names back.
Components
| Component | Where it runs | What it does |
|---|---|---|
Client (krypton) | Your machine | Parses each file (Python, JavaScript, TypeScript, TSX), writes the request, posts it, and keeps the names book. |
| Wire format | Between the two | The request body: flat arrays for the tree, fingerprints for names, line shapes. See Wire format. |
| Scoring server | Hosted | Validates the tree, scores it, returns JSON. Stateless: nothing from a request is stored. See API reference. |
| Engine | The scoring server | Counts decisions and nesting, applies the thresholds, raises flags, writes hints and the purity score. What it measures is in How it works. |
| Names book | Your machine | A map from fingerprint to name, kept on your machine. It is how the answer gets its names back. |
| Order | Your machine | Reads git history locally and sends only file names, token counts and which files each commit touched; the server decides whether a different file order would reuse more of a prompt cache. See file ordering. |
The path of a file
Your machineReads and parses each file, swaps names for hashes, keeps the table, puts names back in the answer.
Over HTTPSStructure and hashes out; numbers and hints back.
Scoring serverChecks the tree, scores it, builds hints, returns JSON, stores nothing.
Only the middle step crosses the network, over HTTPS.
What each side sees
| Item | Stays on your machine | Sent to the scoring server |
|---|---|---|
| Source text | Always | Never |
| Identifiers and strings | The real text, and the names book | A 16-character fingerprint where a name is needed |
| Structure | The full parse | Type, parent and position of every node |
| Lines | The lines themselves | Each line's length and where its visible characters are |
| Imports | The import text | Candidate file paths that exist in the same request |
| Waiver comments | The comment | Whether the line is a comment by itself, and a fingerprint of the reason |
| Credentials, repository | Always | Never |
The limits. The server still sees file paths, the shape of every tree, line lengths and file sizes. Names are keyed with a fresh secret for every scan, so they cannot be recovered by hashing guesses. Two equal names have equal fingerprints, which is what lets the server compare them without reading them.
The scoring server
- Stateless. A request is scored and answered; no tree and no result is stored.
- Strict input. A request is untrusted. Array lengths, parent order, ranges and unknown kinds are checked before anything is scored, and unknown fields are refused so a client typo cannot change a score.
- No client-set thresholds. A client can change file selection and conventions, not the limits or weights, so it cannot read a hidden rating by moving a threshold and watching a flag flip.
- Bounded. There are limits on body size, files per request and nodes per file. See Limits.
How it is checked
- The server's answer is required to equal the command line's answer for the same source, on the engine's own files plus edge cases: Unicode, Windows line endings, byte-order marks, syntax errors, waivers, very deep and very wide files.
- The walker's output is required to equal a reference implementation's, array by array, on 240 files in four languages.
- A test fails if any word of source appears in a request or in the server's answer before the names are put back.
- 400 randomly damaged requests are sent to the server; none may cause a server error.
Ways to run it
| Mode | Where code is read | Network | Status |
|---|---|---|---|
Command line (krypton) | Your machine; the server gets the structure only | HTTPS to the server | Available |
| Demo | The repository you connect is read on the demo's server, in memory, then dropped | HTTPS to GitHub and the server | Live: it builds the trees itself and uses the same server |