Work / Infrastructure / The Infinite Catalog

PHAROS

What if code search had to prove which version of the code every answer came from?

Source auditedPublic repository ↗

The journal

20 exhibits in three rooms

The Grand Atrium

The hall. Its doors lead to every wing.

  1. PHAROSThe Infinite CatalogBuilt
  2. The Mechanical FoundryA concept workshopPlans only
  3. BABELThe Theatre of StoriesPlans only
  4. The Electric GalleryA concept galleryPlans only
  5. ObservatoryThe roof courtyardBuilt
  6. CognitiveOS / ValerieThe Keeper's StudyBuilt
  7. R&BotThe Noir Recording ChamberPlans only

PHAROS: The Infinite CatalogYou are here

Ten machines, one for each thing PHAROS does.

  1. 1. Which repositories has PHAROS really indexed?Pick a repository PHAROS really indexed.RECORDED
  2. 2. What will PHAROS refuse to index?Admit the repository, or refuse it with a reason.RUNS HERE
  3. 3. What does it read from a repository?Read only what Git tracks at that commit.RECORDED
  4. 4. How does it cut code into pieces?Split each file into symbols.RECORDED
  5. 5. What does it turn into vectors, and what does indexing cost?Embed a summary of the code, not the code.RUNS HERE
  6. 6. How does it know who calls whom?Link calls, and leave the doubtful ones unlinked.RECORDED
  7. 7. Which retriever answered, and why that one?Ask, and see which retriever answered.RUNS HERE
  8. 8. What if the code changed after it was indexed?Check the source before handing it over.RUNS HERE
  9. 9. What does an assistant get back?Hand an agent cited, budgeted context.RECORDED
  10. 10. Did it work?What it achieved, and what failed.REPORTED

Valerie: The Keeper's Study

Ten exhibits of how her actions are checked.

  1. 1. What does a model actually hand over?The proposal trayRUNS HERE
  2. 2. What is she allowed to point at?The ticket rackRUNS HERE
  3. 3. Can I throw the switch myself?The paired switchesRUNS HERE
  4. 4. What does a refusal do?The refusal trayRUNS HERE
  5. 5. How do I know what really happened?The receipt printerRUNS HERE
  6. 6. What happens in one turn on the Mac?The desk bellSIMULATED
  7. 7. Would the Mac app do this?The risk ledgerSIMULATED
  8. 8. What happens to text from outside?The memory cabinetSIMULATED
  9. 9. What can she do on a Mac?The instrument consoleSIMULATED
  10. 10. What doesn’t this room show?The gap on the shelfWRITTEN

The machine I built, one step per station

Follow one question through PHAROS.

8 recorded ingestions · 10 exhibits

This room is PHAROS’s pipeline: a repository goes in at the hopper, and cited, verified code comes out for an assistant. Pick a recorded repository, then open any machine and try the experiment at the top. Four run PHAROS’s own code in your browser; the rest replay real runs. What I built and decided is under the room.

Follow the engineering →The book’s contents

RECORDED · PHAROS · 975a38d · 807 files → 7,272 chunks. Replay motion is explanatory, not a captured event log.

What runs here, and what is recorded Enter anywhere. Escape returns to the room.Enter anywhere. Close the book to return to the room.

Repository metrics are recordings. Parsing shows recorded symbols. Search and hashing execute here on the existing fixture; selecting a repository does not turn the fixture into a search of that repository. No external PHAROS service is contacted.

Contents

Next: Admit →

Contents

What’s in this book?

Three passes: a minute, how it works, then the deep dive. Stop after any one. Pick a page to open it in the book, or walk Valerie to a machine in the room.

  1. Pass 1 Overview 1 minute
    1. What problem does PHAROS solve?
    2. What did Ram build, and what changed?
    3. What happens to one question?
    4. Has it really run?
  2. Pass 2 How it works 3 minutes
    1. What’s the idea, in one picture?
    2. Which repositories has PHAROS really indexed?Exhibit 1 RECORDED
    3. What will PHAROS refuse to index?Exhibit 2 RUNS HERE
    4. What does it read from a repository?Exhibit 3 RECORDED
    5. How does it cut code into pieces?Exhibit 4 RECORDED
    6. What does it turn into vectors, and what does indexing cost?Exhibit 5 RUNS HERE
    7. How does it know who calls whom?Exhibit 6 RECORDED
    8. Which retriever answered, and why that one?Exhibit 7 RUNS HERE
    9. What if the code changed after it was indexed?Exhibit 8 RUNS HERE
    10. What does an assistant get back?Exhibit 9 RECORDED
    11. How do the parts connect?
  3. Pass 3 Deep dive As long as you like
    1. Did it work?Exhibit 10 REPORTED
    2. What didn’t work?
    3. How does each part work, exactly?
    4. How did it get here?
    5. What are its limits?
    6. What would Ram test next?

Pass 1 of 3

Overview

What PHAROS solves and why it matters, followed by one real question traced all the way through it. 1 minute

Pass 1 · Overview

What problem does PHAROS solve?

PHAROS gives an AI coding assistant real code it can cite, and proves which version of the code that is before handing it over.

Why it matters. An assistant reading a codebase gets whatever retrieval hands it. A stale chunk looks exactly like a current one, and a confident answer hides which is which. Most code search asks “what looks relevant?”. I built PHAROS around a stricter question: “what can be shown to be true at this commit?”.

  • Measured: held-out nDCG@10 rose from 0.394 to 0.697 and from 0.463 to 0.726 on two locked sets of 101 questions, with a single annotator.
  • Failed: repository memory missed its primary gate. It is shown below at the same size as the win.

Start at the first machine Explore the system

Pass 1 · Overview

What did Ram build, and what changed?

My contribution

What I built
PHAROS itself, in Python and FastAPI: a Tree-sitter indexer for symbols, imports and calls; keyword and dense retrieval fused by rank, with mode routing (the audited auto mode chooses dense, hybrid or keyword; the SPLADE sparse retriever from its earlier search module is implemented, but auto does not route to the sparse retriever); verification of every cited source against its commit; and the REST and native MCP interfaces assistants call. Indexing and embedding run in asynchronous workers, apart from the API.
The tradeoff I chose
Provable over plentiful. When PHAROS can’t verify something, it returns less: a retrieval mode it can’t run fails out loud instead of quietly substituting another, a citation is checked against its Git blob before it is returned, and an ambiguous call stays unlinked rather than guessed. On its own code that leaves about three quarters of calls unlinked. I accepted that cost.
What changed
Held-out nDCG@10 rose from 0.394 to 0.697 and from 0.463 to 0.726 on two locked sets of 101 questionsreported · one annotator. Assistants get code they can cite to a commit, path and line span. And when repository memory missed the gates I set for it before writing it, the miss went on this page, not into a footnote.

Pass 1 · Overview

What happens to one question?

A real question from an AI assistant, followed from start to finish, with the measured time of each stage.

One question, end to end

RECORDED Replayed from a real run on November 2, 2026 at commit 975a38d (MCP trace pharos-verified-context). Nothing is running now.

A real question an assistant sent PHAROS over MCP, followed through every part it touched. Values and timings are from the recording at 975a38d.

10 steps
  1. AssistantAsks a question over MCP

    “how is retrieved source checked against the git blob recorded at index time”

    Tool retrieve_context, scoped to ram-tewari/pharos, at most 5 chunks.

  2. PHAROSChecks who is asking

    The bearer token is parsed and matched to a principal before the tool runs (parse_bearer, principal_for_token, allowed_for).

  3. PHAROSPicks a mode: auto → dense

    Asked for auto. An embedder was available (granite-embedding-english-r2-int8), so auto ran dense retrieval, and the response says so.

  4. PHAROSTurns the question into a vector

    One ONNX call: 4.36 ms.

  5. PHAROSSearches the index by meaning

    Nearest neighbours over pgvector: 12.2 ms, 50 candidates back.

  6. PHAROSKeeps the best 5

    Fused, filtered and hydrated with their spans in 1.84 ms.

    RankSymbolWhere
    1read_blobbackend/app/codeintel/git_source.py:383–406
    2git_sourcebackend/app/codeintel/git_source.py:1–465
    3file_evidencebackend/app/learning/memory.py:52–57
    4read_file_at_commitbackend/app/codeintel/git_source.py:446–461
    5git_blob_shabackend/app/codeintel/source.py:85–86
  7. PHAROSFetches each file at its commit

    5 HTTPS reads from GitHub at 975a38d. With the check, this is the slowest stage: 82.09 ms of 104.43 ms.

  8. PHAROSHashes the bytes the way Git does

    Each file's blob SHA is compared with the one recorded at index time. 5 of 5 matched, so all 5 are returned as verified.

    read_blob verified
    git_source verified
    file_evidence verified
    read_file_at_commit verified
    git_blob_sha verified
  9. PHAROSAssembles cited context

    Each chunk carries its path, line span and commit: about 1,349 tokens, inside the budget.

  10. AssistantGets code it can cite, in 104.43 ms

    Where the time went:

    StageTime
    Embed the question4.36 ms
    Search the index12.2 ms
    Fuse and hydrate1.84 ms
    Fetch and verify source82.09 ms
    Related symbols2.52 ms
    Total104.43 ms
Search took about 18 ms. Proving the code came from the indexed commit took most of the rest, and that check is the point. The full recording, call by call

Pass 1 · Overview

Has it really run?

Four recorded runs, each one told in a few short steps.

Run one question through it

RECORDED

Four real runs, recorded on 2026-11-02 at commit 975a38d (local mac, loopback only; not the deployed service). This page calls no PHAROS service: each step replays what came back.

Ask it a question

“how is retrieved source checked against the git blob recorded at index time”

  1. AssistantAsks over MCP

    retrieve_context, scoped to ram-tewari/pharos, mode auto.

  2. PHAROSSearches by meaning (dense)

    Auto mode could run dense retrieval, so it did, and said so. Top 3 of 5:

    RankSymbolWhere
    1read_blobbackend/app/codeintel/git_source.py:383–406
    2git_sourcebackend/app/codeintel/git_source.py:1–465
    3file_evidencebackend/app/learning/memory.py:52–57
  3. PHAROSChecks every file at its commit

    Each file is re-read at 975a38d and hashed the way Git does. 5 of 5 matched the fingerprint recorded at index time.

    read_blob verified
    git_source verified
    file_evidence verified
  4. AssistantGets cited code

    5 chunks with their path, lines and commit, about 1,349 tokens, inside the budget.

Every piece of code the assistant receives points at a commit, a path and a line span, and was checked against Git first.

The full recording

Give it a hint

The same question, with hints: “git_blob_sha” and “content_mismatch”.

  1. PHAROSHints switch auto to hybrid

    It runs two searches: by name (50 candidates) and by meaning (50).

  2. PHAROSFuses the two rankings

    Reciprocal rank fusion: 1/(60+rank) per list, exact-name boost 1/61, path penalty ×0.7.

    SymbolBy nameBy meaningFused
    git_blob_sha#1#5#1
    git_source#3#2#2
    read_blob#6#1#3
  3. Resultgit_blob_sha moves to the top

    Meaning alone ranked the function that does the comparison #5. Its name ranked it #1, and fused it is #1.

Meaning and names fail differently. Fusing them recovered the exact function, and the response still reports the mode that ran.

The full recording

Tamper with the record

Fetch backend/app/codeintel/source.py:141–162 three ways: honestly, with its fingerprint altered, and with none on record.

  1. PHAROSThe SHA recorded at index time

    The bytes match. The code is returned, verified.

    resolved
  2. PHAROSThe recorded SHA with its first hex digit changed

    The bytes don’t match. The code is withheld, and the reason is returned instead.

    unavailable:content_mismatch
  3. PHAROSNo SHA on record

    Nothing to compare against. The code is returned, marked unverified.

    resolved

A mismatch withholds the code instead of returning something that only looks right. Integrity is not correctness: a match proves the bytes, not the logic.

The full recording

Take away the embedder

The same question, on a server with no embedding model, asked four ways.

  1. PHAROSmode: auto

    Auto falls back to keyword and warns: “dense retrieval unavailable (no embedding backend configured (EMBEDDING_BACKEND=none)); used keyword retrieval only”.

    degraded
  2. PHAROSmode: dense

    Refused with ModeUnavailable: no embedding backend configured (EMBEDDING_BACKEND=none).

    refused
  3. PHAROSmode: hybrid

    Refused with ModeUnavailable: no embedding backend configured (EMBEDDING_BACKEND=none).

    refused
  4. PHAROSmode: graph

    Refused with ModeUnavailable: no embedding backend configured (EMBEDDING_BACKEND=none).

    refused

Auto may degrade, but it says so. A mode you ask for by name is never silently swapped for a weaker one.

The full recording

Pass 2 of 3

How it works

The idea behind PHAROS, and then the room’s ten exhibits, in the order a repository flows through them. 3 minutes

Pass 2 · How it works

What’s the idea, in one picture?

Picture a librarian who files every page by the edition it came from, finds pages by meaning or by name, and checks the edition stamp before handing one over. If the stamp doesn’t match, you get nothing, not the wrong page.

  1. 01File it

    Code is cut along its own structure, into functions and classes, and filed under the commit it came from.

  2. 02Keep pointers

    The database keeps where code is, its vectors and who calls whom. The code itself stays in Git.

  3. 03Find, then check

    A question is answered by meaning, by name or both. Then each file is re-read at its commit and its fingerprint compared.

  4. 04Hand it over

    An assistant gets cited code through the same tool calls it uses for anything else.

Pass 2 · How it works · Exhibit 1 of 10 · The intake hopper RECORDED

Which repositories has PHAROS really indexed?

Pick a repository PHAROS really indexed.

Try Pick a repository from the shelf. Which part of indexing it took longest?

Choose a repository

ram-tewari/PHAROS at 975a38d

Files indexed
807 of 1,576 tracked
Chunks
7,272
Lines
222,275
Graph edges
14,712
Wall time
402.9 s

Languages indexed: Python 441, TypeScript 354, JavaScript 6, C 2, Java 1, C++ 1, Rust 1, Go 1. Skipped: 712 not source, 57 excluded path.

CheckoutParseEmbedDatabase writeGraph
2.323 s1.501 s368.889 s28.836 s1.229 s

Indexed in this site's audit on 2026-11-02: PHAROS at 975a38d, macOS arm64, CPU only, granite-embedding-english-r2-int8, PostgreSQL 17.11 with pgvector 0.8.7.

pallets/click at 2247b35

Files indexed
91 of 178 tracked
Chunks
1,517
Lines
30,383
Graph edges
3,465
Wall time
278.7 s

Languages indexed: Python 91. Skipped: 87 not source.

CheckoutParseEmbedDatabase writeGraph
0.016 s0.333 s271.053 s7.183 s0.114 s

Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.

sindresorhus/ky at 3541888

Files indexed
98 of 115 tracked
Chunks
997
Lines
36,231
Graph edges
1,672
Wall time
118.9 s

Languages indexed: TypeScript 98. Skipped: 17 not source.

CheckoutParseEmbedDatabase writeGraph
0.023 s0.3 s113.707 s4.803 s0.054 s

Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.

dtolnay/anyhow at bb1b0f9

Files indexed
37 of 54 tracked
Chunks
438
Lines
5,857
Graph edges
622
Wall time
60.4 s

Languages indexed: Rust 37. Skipped: 17 not source.

CheckoutParseEmbedDatabase writeGraph
0.024 s0.087 s58.075 s2.162 s0.05 s

Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.

curl/curl at 87c4c6d

Files indexed
1,117 of 4,545 tracked
Chunks
9,424
Lines
316,221
Graph edges
32,130
Wall time
703.6 s

Languages indexed: C 1,060, Python 55, C++ 2. Skipped: 3,428 not source.

CheckoutParseEmbedDatabase writeGraph
0.024 s1.836 s659.763 s40.736 s1.137 s

Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.

go-chi/chi at 9f8adb1

Files indexed
89 of 110 tracked
Chunks
578
Lines
13,152
Graph edges
1,577
Wall time
106.2 s

Languages indexed: Go 89. Skipped: 21 not source.

CheckoutParseEmbedDatabase writeGraph
0.012 s0.167 s103.27 s2.652 s0.057 s

Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.

google/gson at 5773104

Files indexed
264 of 313 tracked
Chunks
4,345
Lines
57,131
Graph edges
8,681
Wall time
754.2 s

Languages indexed: Java 264. Skipped: 49 not source.

CheckoutParseEmbedDatabase writeGraph
0.023 s0.7 s730.578 s22.422 s0.39 s

Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.

immerjs/immer at 75a290e

Files indexed
57 of 169 tracked
Chunks
474
Lines
17,865
Graph edges
1,010
Wall time
77.7 s

Languages indexed: TypeScript 29, JavaScript 28. Skipped: 112 not source.

CheckoutParseEmbedDatabase writeGraph
0.032 s0.203 s74.996 s2.416 s0.033 s

Reported by PHAROS in its retrieval benchmark, run 2026-10-30 by its code at 0b01729 on arm 18 CPUs, 36 GiB, none (CPU only), granite-embedding-english-r2-int8. Not rerun here.

Eight indexing runs: PHAROS itself, and seven open-source repositories from its retrieval benchmark. Every number on a spine was recorded when PHAROS indexed that commit.

Ingestion jobs in the explorer

Pass 2 · How it works · Exhibit 2 of 10 · The intake hopper RUNS HERE

What will PHAROS refuse to index?

Admit the repository, or refuse it with a reason.

Try Type a repository URL. Try one that starts with http:// and see why it is refused before anything is cloned.

ReferenceVerdictRaised at
https://github.com/pallets/clickadmitted as https://github.com/pallets/click—
pallets/clickadmitted as https://github.com/pallets/click—
javascript:alert(1)refused: “malformed repository URL”:157
http://github.com/pallets/clickrefused: “only https:// repository URLs are accepted”:159
https://token@github.com/pallets/clickrefused: “credentials in repository URLs are not accepted; configure GIT_CLONE_TOKEN instead”:161
https://github.com:8443/pallets/clickrefused: “custom ports are not accepted in repository URLs”:165
https://github.com/pallets/click?tab=readmerefused: “repository URLs must not contain a query or fragment”:167
https://127.0.0.1/pallets/clickrefused: “IP-address hosts are not accepted”:170
https://example.com/pallets/clickrefused: “host 'example.com' is not in CODEINTEL_ALLOWED_GIT_HOSTS”:173
https://github.com/pallets/click/tree/mainrefused: “expected a URL of the form https://host/owner/repo”:179
/home/me/reporefused: “local repositories can only be indexed from the CLI”:144

Before anything is cloned, PHAROS checks the reference. Type any repository URL: this is PHAROS's own check, ported line for line and running in your browser.

Ingestion jobs in the explorer

Pass 2 · How it works · Exhibit 3 of 10 · The intake hopper RECORDED

What does it read from a repository?

Read only what Git tracks at that commit.

Try Drag the time dial to replay the clone, and watch the hopper and the counters follow it.

Replay: PHAROS

RECORDED

Tracked
1,576
Indexed
807
Not source
712
Excluded
57
  1. .github/workflows/ci.yml not source
  2. .kiro/hooks/external-discovery-cache-invalidation.json not source
  3. .kiro/specs/README.md not source
  4. .kiro/specs/backend/ml-model-training/tasks.md not source
  5. .kiro/specs/backend/phase11-5-ml-benchmarking/design.md not source
  6. .kiro/specs/backend/phase12-fowler-refactoring/tasks.md not source
  7. .kiro/specs/backend/phase16-7-missing-features-implementation/requirements.md not source
  8. .kiro/specs/backend/phase19-hybrid-edge-cloud-orchestration/SECURITY_UPDATES.md not source

The names are a sample, about one in every 14 tracked files at the pinned commit; each verdict is PHAROS's ported skip rule. Counts and times are the recorded run's. Times are compressed.

Change PHAROS's fixture and re-index

RUNS HERE

Sixteen files of PHAROS's test repository, each hashed as a Git blob in your browser. Change one and only it is re-indexed; the rest only move their commit pointer (indexer.py:245).

  • android/src/com/tinyshop/CartActivity.java unchanged
  • native/c/checksum.c unchanged
  • native/c/checksum.h unchanged
  • native/cpp/geometry.cpp unchanged
  • native/src/lib.rs unchanged
  • shop/__init__.py unchanged
  • shop/api.py unchanged
  • shop/auth.py unchanged
  • shop/cart.py unchanged
  • shop/db.py unchanged
  • tests/test_cart.py unchanged
  • tools/ratelimit/limiter.go unchanged
  • web/client.js unchanged
  • web/format.js unchanged
  • web/session.ts unchanged
  • web/types.ts unchanged

PHAROS lists the files Git tracks at the exact revision, skips what is not source code, and on a re-index touches only files whose blob SHA changed. Replay the repository you chose, then change PHAROS's own fixture and watch the diff.

For engineersOpen detail
  • A bare shallow clone is read with git cat-file at a pinned commit, so symlinks and submodules cannot escape the repository, and repository code is parsed, never run.
  • Remote repositories must be https on an allowlisted host. Local paths can only be registered through the CLI, so API callers cannot reach the worker's filesystem.
  • Jobs live in PostgreSQL with atomic claims and retries. Read the claim.
  • Files are compared by Git blob SHA. Unchanged files only move their commit pointer. Read the diff.
  • The last commit is written after everything else, so a failed run leaves the previous index searchable. Read the run.

The indexer in the explorer

Pass 2 · How it works · Exhibit 4 of 10 · The branching manuscript RECORDED

How does it cut code into pieces?

Split each file into symbols.

Try Pick a symbol and see the exact lines PHAROS cut for it.

Choose a file

shop/auth.py

RECORDED

"""Password hashing and session tokens.""" import hashlibimport hmacimport secretsimport time from .db import fetch_user TOKEN_TTL_SECONDS = 3600  def hash_password(password: str, salt: bytes | None = None) -> str:    """Derive a salted PBKDF2 hash for storing a user's password."""    salt = salt or secrets.token_bytes(16)    digest = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, 200_000)    return salt.hex() + ":" + digest.hex()  def verify_password(password: str, stored: str) -> bool:    """Check a plaintext password against a stored PBKDF2 hash in constant time."""    salt_hex, digest_hex = stored.split(":", 1)    candidate = hash_password(password, bytes.fromhex(salt_hex))    return hmac.compare_digest(candidate.split(":", 1)[1], digest_hex)  def authenticate(username: str, password: str) -> dict | None:    """Log a user in: look them up and verify the password."""    user = fetch_user(username)    if user is None or not verify_password(password, user["password_hash"]):        return None    return user  class TokenSigner:    """Issues and validates HMAC-signed session tokens."""     def __init__(self, secret: bytes):        self.secret = secret     def issue(self, user_id: int, now: float | None = None) -> str:        """Create a signed token that expires after TOKEN_TTL_SECONDS."""        expires = int((now or time.time()) + TOKEN_TTL_SECONDS)        payload = f"{user_id}.{expires}"        return payload + "." + self._sign(payload)     def verify(self, token: str, now: float | None = None) -> int | None:        """Return the user id for a valid, unexpired token, else None."""        try:            user_id, expires, signature = token.rsplit(".", 2)        except ValueError:            return None        if not hmac.compare_digest(signature, self._sign(f"{user_id}.{expires}")):            return None        if int(expires) < (now or time.time()):            return None        return int(user_id)     def _sign(self, payload: str) -> str:        return hmac.new(self.secret, payload.encode(), hashlib.sha256).hexdigest()

9 chunks: one per function, class and method, plus the module. Parser: Python ast.

web/session.ts

RECORDED

import { Session } from "./types"; /** Decode the expiry embedded in a session token ("<user>.<expires>.<sig>"). */export function tokenExpiry(token: string): number {  const [, expires] = token.split(".");  return Number(expires) * 1000;} /** Keeps the current session and refreshes it shortly before it expires. */export class SessionManager {  private session: Session | null = null;   /** True when there is a session whose token has not expired yet. */  isLoggedIn(now: number = Date.now()): boolean {    return this.session !== null && tokenExpiry(this.session.token) > now;  }   start(session: Session): void {    this.session = session;  }}

5 chunks: one per function, class and method, plus the module. Parser: tree-sitter.

native/src/lib.rs

RECORDED

//! Native helpers for tinyshop. use std::fmt; /// CRC-32 (IEEE) checksum used to verify uploaded product images.pub fn crc32(data: &[u8]) -> u32 {    let mut crc: u32 = 0xFFFF_FFFF;    for &byte in data {        crc ^= byte as u32;        for _ in 0..8 {            let mask = (!(crc & 1)).wrapping_add(1);            crc = (crc >> 1) ^ (0xEDB8_8320 & mask);        }    }    !crc} /// A money amount in integer cents.pub struct Cents(pub i64); impl fmt::Display for Cents {    /// Format cents as dollars, e.g. `1250` -> `$12.50`.    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {        write!(f, "${}.{:02}", self.0 / 100, self.0 % 100)    }}

5 chunks: one per function, class and method, plus the module. Parser: tree-sitter.

tools/ratelimit/limiter.go

RECORDED

// Package ratelimit throttles API clients with a token bucket.package ratelimit import (	"sync"	"time") // Bucket is a token-bucket rate limiter.type Bucket struct {	mu       sync.Mutex	capacity float64	tokens   float64	rate     float64	last     time.Time} // NewBucket creates a bucket that refills `rate` tokens per second.func NewBucket(capacity, rate float64) *Bucket {	return &Bucket{capacity: capacity, tokens: capacity, rate: rate, last: time.Now()}} // Allow reports whether one request may proceed, consuming a token if so.func (b *Bucket) Allow() bool {	b.mu.Lock()	defer b.mu.Unlock()	b.refill(time.Now())	if b.tokens < 1 {		return false	}	b.tokens--	return true} // refill adds tokens for the time elapsed since the last call.func (b *Bucket) refill(now time.Time) {	elapsed := now.Sub(b.last).Seconds()	b.tokens = min(b.capacity, b.tokens+elapsed*b.rate)	b.last = now}

5 chunks: one per function, class and method, plus the module. Parser: tree-sitter.

android/src/com/tinyshop/CartActivity.java

RECORDED

package com.tinyshop; import java.util.ArrayList;import java.util.List; /** Android screen listing the items in the cart. */public class CartActivity {    private final List<String> skus = new ArrayList<>();     /** Called when the user taps "remove" next to an item. */    public void onRemoveClicked(String sku) {        skus.remove(sku);        refreshList();    }     private void refreshList() {        System.out.println("cart now has " + skus.size() + " items");    }}

4 chunks: one per function, class and method, plus the module. Parser: tree-sitter.

app/models/order.rb Ruby has no grammar in PHAROS

RUNS HERE

  1. order.rb:1-60 first line: puts 'line 1'
  2. order.rb:51-110 first line: puts 'line 51'
  3. order.rb:101-130 first line: puts 'line 101'

Windows of 60 lines overlapping by 10, recorded as line-fallback with the reason unsupported_language.

In the run you chose, PHAROS:

Each function, class and method becomes its own chunk with exact line numbers. Pick a file from PHAROS's fixture to see what its parser returned; a language with no grammar is cut into overlapping line windows, live, and the fallback is recorded rather than hidden.

For engineersOpen detail
  • Python uses the standard library's ast. JavaScript, TypeScript, Go, Rust, C, C++ and Java use tree-sitter. Read the dispatch.
  • Ruby, PHP, Swift, Kotlin, Scala and C# have no grammar wired up, and their files use line windows recorded as fallback.

The parsers in the explorer

Pass 2 · How it works · Exhibit 5 of 10 · The sorted shelves RUNS HERE

What does it turn into vectors, and what does indexing cost?

Embed a summary of the code, not the code.

Try Pick another symbol and watch which dimensions of its vector are set.

The text that is embedded

RUNS HERE

[python] shop/auth.py :: hash_password
def hash_password(password: str, salt: bytes | None) -> str:
    """Derive a salted PBKDF2 hash for storing a user's password."""
    salt = salt or secrets.token_bytes(16)
    digest = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, 200_000)
    return salt.hex() + ":" + digest.hex()
    calls: [token_bytes, pbkdf2_hmac, encode, hex]

The tokens keyword search indexes

RUNS HERE

Name tokens three times, path tokens twice, then everything else once.

hash password hashpassword hash password hashpassword hash password hashpassword shop auth py shop auth py hash password hashpassword str salt bytes none derive salted pbkdf2 storing user token tokenbytes hmac pbkdf2hmac encode hex secrets digest hashlib

Its hash-v1 vector

RUNS HERE

768 dimensions. PHAROS's offline lexical embedder: words and word pairs hashed into buckets. It is not semantic; production uses Granite int8.

What embedding cost in PHAROS

RECORDED

What gets embedded is a short text built from the symbol: its file and name, signature, docstring, up to 25 lines of body and the calls it makes. Pick a symbol: the text, the full-text tokens and an offline hash vector are built in your browser by PHAROS's own code.

For engineersOpen detail
  • A chunk is embedded from its signature, docstring, calls and first body lines, not raw source. Read the summary.
  • HNSW serves vectors and GIN serves full text. Read the indexes.
  • The tradeoff is real: the project measures pointer storage as saving about 5% of the database, because vectors and their index dominate.

Embeddings in the explorer

What indexing does to a repository

RECORDED Replayed from a real run on November 2, 2026 at commit 975a38d (self-index run, macOS arm64, CPU only). Nothing is running now.

PHAROS indexing its own repository at 975a38d: which files it keeps, what it cuts them into, and where the 402.9 s went.

7 steps
  1. PHAROSChecks out the commit

    1,576 tracked files at 975a38d, in 2.3 s.

  2. PHAROSKeeps only source

    712 are not source (docs, specs, configs) and 57 sit on excluded paths. 807 files remain.

  3. PHAROSParses each file into its syntax tree

    222,275 lines in 1.5 s. No file fell back to plain line splitting.

  4. PHAROSCuts at function and class boundaries

    7,272 chunks, each a whole symbol with its path and line span, never a window cut mid-function.

  5. PHAROSEmbeds every chunk

    368.9 s of the 402.9 s, on a CPU with no GPU. By far the slowest step.

  6. PHAROSWrites the index

    Chunks, vectors and blob SHAs into Postgres with pgvector in 28.8 s.

  7. PHAROSLinks calls it can prove

    6,977 calls resolved, 17,764 left unresolved and 2,888 ambiguous: a call is linked only when PHAROS can tell which function it means. 1.2 s.

    StageTime
    Checkout2.3 s
    Parse1.5 s
    Embed368.9 s
    Write28.8 s
    Call graph1.2 s
    Total402.9 s
Indexing is mostly embedding. Everything else, from checkout to the call graph, took under a minute. Run the parser yourself, in the PHAROS room

Pass 2 · How it works · Exhibit 7 of 10 · The lit stacks RUNS HERE

Which retriever answered, and why that one?

Ask, and see which retriever answered.

Try In Auto, switch the embedder off, then force Dense. One falls back with a warning; the other refuses.

Mode

Keyword BM25

    Dense cosine

      What PHAROS returns

        Fusion adds 1/(60 + rank) from each list (retrieval.py:431), plus 1/61 when the question names the symbol (:446); tests, docs and examples are then multiplied by 0.7 unless asked for (:511).

        Recorded from PHAROS: “verify a user's password”, hybrid

        RECORDED

        #SymbolKeyword rankDense rankScore
        1shop.auth.authenticate210.0325
        2shop.auth.verify_password130.0323
        3shop.db.save_user520.0315
        4shop.auth.TokenSigner.verify350.0313
        5shop.auth.hash_password470.0306

        PHAROS's Retriever at 975a38d on its tinyshop fixture, SQLite, hash-v1 embedder. The page reproduces this ranking exactly.

        RECORDED

        The lit stacks

        The same question, ranked two ways.

        How is retrieved source checked against the Git blob? One recorded question, chosen for this page. It is not a quality measurement.

        RankDense, no hintsHybrid, with hints
        1git_source.Checkout.read_blobsource.git_blob_sha
        2git_sourcegit_source
        3learning.memory.file_evidencegit_source.Checkout.read_blob
        4git_source.read_file_at_commitsource
        5source.git_blob_shagit_source.Checkout._git

        RECORDED Captured from a real run on November 2, 2026. Nothing is running now.

        Lights respond to the recorded answer. This is not a new search.

        See the scores Step through a whole question

        auto prefers the dense retriever, switches to hybrid when the caller passes identifier hints, and falls back to keyword with a warning when dense cannot run. Search PHAROS's fixture with its own retrieval code, switch the embedder off, and watch two rankings fuse.

        For engineersOpen detail
        • Keyword is PostgreSQL full-text. Dense is pgvector cosine through HNSW. Hybrid is reciprocal rank fusion with k=60, plus an exact-name boost of 1/61. Read the fusion.
        • Tests, docs and examples are multiplied by 0.7 after fusion, unless the question asks for them. Read the penalty.
        • With no embedder, auto degrades to keyword with a warning, and asking for dense is refused. See it happen.
        • Scope is a filter the caller chooses. A call naming no repository searches the whole index.
        • The page searches with SQLite's path (Python BM25 and exact cosine), which PHAROS uses without PostgreSQL. The service ranks keywords with ts_rank_cd instead.

        The hybrid run, step by step

        How auto picks a retrieval mode

        RUNS HERE PHAROS’s mode routing, ported to the browser at 975a38d (packages/pharos-web) runs in this page. No service, model or device is involved.

        Choose what the caller asks for and what the server has. PHAROS’s own routing, ported to this page, decides; the diagram shows the route it took and what it returned. The SPLADE sparse retriever is implemented in PHAROS, but auto never routes to it, so it is not on this map.

        6 steps
        1. CallerAsks for a mode

          auto, or a mode by name, with or without hints. The router first asks whether dense retrieval can run: is there an embedder, and was the index embedded with the same model?

        2. Routerauto, embedder ready, no hints: dense

          Search by meaning, and the response says dense was used.

        3. Routerauto with hints: hybrid

          Two searches, by name and by meaning, fused by reciprocal rank, plus a boost for an exact symbol name.

        4. Routerauto without a usable embedder: keyword, with a warning

          It degrades, and says so in the response: “dense retrieval unavailable (…); used keyword retrieval only”.

        5. Routerkeyword by name: keyword

          Asked for by name, it needs no embedder, so it runs as asked.

        6. RouterA named mode that can’t run: refused

          Dense or hybrid asked for by name, with no usable embedder, fails with ModeUnavailable. It is never quietly swapped for a weaker mode.

        auto may degrade, and says so. A mode you name either runs or fails out loud. The same refusals, recorded on the real server

        Ask PHAROS about its own code The same retrieval, in your browser, over the index PHAROS built of itself.

        Pass 2 · How it works · Exhibit 8 of 10 · The magnifying lectern RUNS HERE

        What if the code changed after it was indexed?

        Check the source before handing it over.

        Try Change one character of the source, and watch PHAROS refuse to hand it over. Then put it back.

        backend/app/codeintel/source.py at 975a38d MIT licence. Lines 141–162 are _resolve_one.

        Expected, from Git's tree
        c9f05cf7bf871b09919d64e9fdaf8380ecc3df2c
        Hashed now, in your browser
        …
        Expected SHAStatusCode returnedVerified
        The SHA recorded at index timeresolvedyesyes
        The recorded SHA with its first hex digit changedunavailable:content_mismatchnono
        No SHA on recordresolvedyesno

        RECORDED Captured from a real run on November 2, 2026. Nothing is running now.

        Check the expected SHA yourself: git rev-parse 975a38d:backend/app/codeintel/source.py

        PHAROS fetches the file at the indexed commit and hashes it the way Git does. Change one character below and it refuses to return the code.

        The recorded integrity cases Source verification in the explorer

        Tamper with the record

        RECORDED Replayed from a real run on November 2, 2026 at commit 975a38d (integrity cases pharos-integrity-cases). Nothing is running now.

        The same 22 lines, backend/app/codeintel/source.py:141–162, fetched three times: with the fingerprint recorded at index time, with that fingerprint altered by one digit, and with none on record.

        5 steps
        1. PHAROSFetches the file at the indexed commit

          backend/app/codeintel/source.py:141–162 at 975a38d.

        2. PHAROSHashes the bytes the way Git does

          The actual blob SHA is c9f05cf7bf871b09919d64e9fdaf8380ecc3df2c.

        3. Case 1The SHA recorded at index time

          The two fingerprints match. The code is returned, marked verified.

          resolved
        4. Case 2The recorded SHA with its first hex digit changed

          Recorded 09f05cf7bf87…, actual c9f05cf7bf87…. The code is withheld and the reason returned instead.

          unavailable:content_mismatch
        5. Case 3No SHA on record

          Nothing to compare against. The code is returned, but marked unverified, never as verified.

          resolved verified: false
        A one-digit change to the record withholds the code instead of returning something that only looks right. A match proves the bytes, not that the code is correct. The full recording

        Pass 2 · How it works · Exhibit 9 of 10 · The trace journal RECORDED

        What does an assistant get back?

        Hand an agent cited, budgeted context.

        Try Open the recorded answer an assistant received, and follow one citation to its commit.

        The assistant asks

        RECORDED

        retrieve_context(
          query="how is retrieved source checked against the git blob recorded at index time",
          repository="ram-tewari/pharos",
          max_chunks=5,
          include_memory=false
        )

        PHAROS answers

        RECORDED

        # Code context for: how is retrieved source checked against the git blob recorded at index time
        
        ## [1] backend.app.codeintel.git_source.Checkout.read_blob (method) — ram-tewari/pharos:backend/app/codeintel/git_source.py:383-406
           ✓ source verified at the commit; code returned
        
        ## [2] backend.app.codeintel.git_source (module) — ram-tewari/pharos:backend/app/codeintel/git_source.py:1-465
           ✓ source verified at the commit; code returned
        
        ## [3] backend.app.learning.memory.file_evidence (function) — ram-tewari/pharos:backend/app/learning/memory.py:52-57
           ✓ source verified at the commit; code returned
        
        ## [4] backend.app.codeintel.git_source.read_file_at_commit (function) — ram-tewari/pharos:backend/app/codeintel/git_source.py:446-461
           ✓ source verified at the commit; code returned
        
        ## [5] backend.app.codeintel.source.git_blob_sha (function) — ram-tewari/pharos:backend/app/codeintel/source.py:85-86
           ✓ source verified at the commit; code returned
        
        ## Related code (call graph)
        - imported_by: backend.app.cli — backend/app/cli.py:1-463
        - imported_by: backend.app.codeintel.context — backend/app/codeintel/context.py:1-360
        - imported_by: backend.app.codeintel.indexer — backend/app/codeintel/indexer.py:1-563
        - imported_by: backend.app.codeintel.jobs — backend/app/codeintel/jobs.py:1-302
          … and 8 more
        Characters
        5,396
        About tokens
        1,349
        Truncated
        no
        Retrieval
        18.41 ms
        Verifying source
        82.09 ms

        Headings rebuilt in PHAROS's own format (context.py:321) from the recorded fields. The code bodies were verified and returned but not stored here; the full text's SHA-256 is c4b4be41c1a6887e…. Mode used: dense.

        RECORDED Captured from a real run on November 2, 2026. Nothing is running now.

        Step through the call, function by function

        The eight tools an assistant can call

        SOURCE-DERIVED

        retrieve_context
        Ranked functions and classes with verified source, their callers and callees, and what PHAROS learned about the repository.
        search_code
        Chunk pointers (path, lines, symbol) with retrieval evidence, no code. auto, keyword, dense, hybrid or graph.
        find_symbol
        Where a symbol is defined, with its callers and callees.
        get_repo_brief
        What the repository is, its layout, main modules and strongest conventions, in at most 2,200 characters.
        search_memory
        Conventions, files that change together, and history, learned from the repository.
        list_skills
        How recurring changes are made in the repository, one line each.
        get_skill
        One playbook: its steps and example commits.
        list_repositories
        Indexed repositories with their commit, language coverage and status.

        All read-only, over streamable HTTP (native_server.py:79).

        An assistant calls PHAROS over MCP and gets back ranked code it can cite: each chunk with its repository, path and lines, the code itself when it verified, and related functions from the graph, cut to a character budget.

        The recorded MCP call, step by step

        Pass 2 · How it works

        How do the parts connect?

        All twelve parts of the system on a single map. Pick any part to see what it hands on to the next one.

        PHAROS, in twelve partsOpen diagram
        1. 01 File it Index

        2. 02 Keep pointers Store

        3. 03 Find, then check Serve

        4. 04 Hand it over Interface

        Source verification Recorded run

        Re-reads the file at its commit and checks its Git fingerprint before anything is returned.

        Its deep dive
        Every connection, as a table
        PHAROS, in twelve parts: every connection, equivalent to the map
        FromHands overTo
        Ingestion jobsrunsIndexer
        Indexerparses withParsers
        Indexerembeds withEmbeddings
        IndexerrebuildsCall graph
        ParserschunksPostgreSQL store
        EmbeddingsvectorsPostgreSQL store
        Call graphedgesPostgreSQL store
        PostgreSQL storesearched byRetriever
        Retrieverranked hitsContext assembly
        Source verificationverified codeContext assembly
        Repository memorymemory blockContext assembly
        Context assemblyretrieve_contextMCP server
        Context assembly/context/retrieveREST API
        Retrieversearch_codeMCP server
        Retriever/search/codeREST API

        Integrity checking proves the bytes match the indexed commit. It says nothing about whether the code is correct or secure.

        Pass 3 of 3

        Deep dive

        Whether it worked and what failed, every part with its source code, and how the project got to where it is. As long as you like

        Pass 3 · Deep dive · Exhibit 10 of 10 · The curtained shelf REPORTED

        Did it work?

        What it achieved, and what failed.

        Try Put the retrieval gain beside the memory gate that failed.

        Retrieval improved on questions it had never seen

        REPORTED

        nDCG@10 on two locked held-out sets, 101 questions over 7 repositories
        nDCG@10 on two locked held-out sets, 101 questions over 7 repositories
        Held-out setBeforeAfter
        Held-out set 10.3940.697
        Held-out set 20.4630.726

        Reported From PHAROS's benchmark report, not rerun here. One annotator, who also built the system; CPU. nDCG@10 scores how close the right code sits to the top, from 0 to 1.

        Repository memory v1 failed its primary gates

        REPORTED

        GateTargetResultVerdict
        Precision of what memory claims (audited)90%55%✕ failed
        Primary: source-file recallmust improve0.827 → 0.823✕ failed
        Repository questions answered (secondary)reported5 → 14 of 30secondary measure
        File-selection precision, 80 tasks (secondary)reported63.4% → 77.5%secondary measure

        Reported The precision and recall gates failed, so memory v1 is not a success, whatever the secondary measures say. The file-precision figure is owner-confirmed and stays beside the gates that failed.

        15 milestones, each linked to its commit

        SOURCE-LINKED

        1. Similarity moves into pgvector
        2. The knowledge-management product is removed
        3. Module boundaries become a CI gate
        4. A real MCP server
        5. Today's core: chunk-level indexing and hybrid retrieval
        6. Migrations squashed, code index schema added
        7. Two tokens, and working MCP on the new core
        8. Retrieval gets a benchmark
        9. Free deployment with CPU embeddings
        10. Granite embeddings and dense by default
        11. Query embedding can run off the host
        12. The memory evaluation is locked first
        13. Memory fails its locked evaluation
        14. Memory claims must prove themselves
        15. The second evaluation stops with no verdict

        Retrieval improved on held-out questions. Repository memory did not pass its own gates, and it stays here at the same size as the success.

        The full history

        I locked two held-out sets of code questions across seven repositories before the final measurement, and ran each once.

        Reported nDCG@10 on two locked held-out sets, 101 questions in total
        Reported nDCG@10 on two locked held-out sets, 101 questions in total
        Held-out setBaselineImproved
        Held-out set 10.3940.697
        Held-out set 20.4630.726

        Reported One annotator, CPU. From the project’s own evaluation; not rerun for this site.

        nDCG@10 scores how close the right code sits to the top of the results, from 0 to 1.

        What it cost. Questions that name the API scored slightly lower without hints, 0.987 → 0.907 and 0.982 → 0.931, because dense retrieval ranks most named symbols first but not all. Passing hints brought the first set back to 0.991. Reported

        How it works7 claims, each with how it is known
        • PHAROS indexes committed code using AST-aware chunks and incremental blob-SHA checks.

          Source verifiedLedger

        • PHAROS supports keyword, dense, hybrid and graph retrieval; auto prefers dense, hybrid with hints, keyword fallback with warnings.

          Source verifiedLedger

          Explicit unavailable semantic modes fail; auto can degrade with a warning. Repository scope is a filter the caller chooses; a call naming no repository searches the whole index.

        • Implemented dense, SPLADE sparse and lexical retrieval with reciprocal-rank fusion.

          Owner confirmedLedger

          In the commit audited for this site, auto mode does not route to the sparse retriever.

        • Source context is checked against the indexed Git blob SHA.

          Source verifiedLedger

          Integrity checking is not semantic code correctness or security certification.

        • Call/import graph resolution is conservative; ambiguous calls remain unresolved.

          Source verifiedLedger

        • Native MCP exposes search, context, symbol, repository and repository-memory tools.

          Source verifiedLedger

        • PHAROS runs indexing and embedding in asynchronous workers separate from its cloud API, with GitHub-referenced source storage to limit duplicated repository data.

          Owner confirmedLedger

          The deployed service was not inspected for this site.

        A line marked owner confirmed is stated on my November 2026 résumé. It is my own account, and it was not re-measured for this site.

        Measured and recorded6 claims, each with how it is known
        • Reported nDCG@10 improved 0.394 to 0.697 and 0.463 to 0.726 on two locked held-out sets totaling 101 questions.

          ReportedLedger

          Seven repositories and languages, single annotator, CPU. Read from project documentation; not reproduced for this site.

        • After retrieval phase 1, questions that name the API scored slightly lower without hints (nDCG@10 0.987 → 0.907 and 0.982 → 0.931); hints brought the first set back to 0.991.

          ReportedLedger

          From the retrieval phase 1 report at 975a38d. Shown beside the result as its recorded cost.

        • In a recorded run at commit 975a38d, a question sent through native MCP returned five chunks, each fetched from GitHub and matched against its indexed Git blob.

          Recorded runLedger

          One local run with a question chosen by the author. Not a benchmark and not the deployed service.

        • In a recorded run, changing the expected blob SHA made PHAROS withhold the source and report a content mismatch.

          Recorded runLedger

          With no SHA on record, source is returned marked unverified.

        • In a recorded run with no embedder, auto used keyword retrieval with a warning, and explicit dense, hybrid and graph modes were refused.

          Recorded runLedger

        • Indexing PHAROS at commit 975a38d resolved 6,977 calls and left 17,764 unresolved and 2,888 ambiguous.

          Recorded runLedger

          Most unresolved calls reach the standard library or dependencies. PHAROS leaves them unlinked by design.

        Pass 3 · Deep dive

        What didn’t work?

        Repository memory v1 failed its primary gates.

        Audited precision
        55%
        Primary source-file recall
        0.827 to 0.823
        Repo Q&A, secondary only
        5 to 14 of 30
        File precision, secondary only
        0.634 to 0.775

        I wrote the gates before any memory code existed. Repo Q&A and file precision improved, but neither was the primary metric. A secondary win does not rescue a failed primary gate, so the numbers stay together, at the same size as the success. That is the point of setting the bar first.

        The two claims, with how each is known2 claims, each with how it is known
        • Repository memory v1 failed its primary source-file recall and precision gates; audited precision was 55%.

          ReportedLedger

          Primary source-file recall went from 0.827 to 0.823. Repo Q&A, a secondary measure, improved from 5 to 14 of 30.

        • In an 80-task evaluation of Git-history memory, file-selection precision rose from 63.4% to 77.5%, while unsupported memory claims were audited.

          Owner confirmedLedger

          Memory v1 still failed its primary gates: audited precision was 55%, and primary source-file recall did not improve.

        A line marked owner confirmed is stated on my November 2026 résumé. It is my own account, and it was not re-measured for this site.

        Smaller findings from these recordings

        • Dense retrieval ranked the function that does the comparison fifth for a question about exactly that. Hints moved it to first, and the project reports that hints help less on code a model has not seen.
        • On PHAROS's own code, the graph resolved about a quarter of attempted calls. Most of the rest reach libraries, and that is the cost of never guessing.
        • Concurrent source fetches can read the same file more than once, because the cache has no single-flight.

        Pass 3 · Deep dive

        How does each part work, exactly?

        Every part of the system, where its responsibility ends, and how each of those facts is known.

        Each part below opens to what it does, where it stops, and how that is known: its pinned source at 975a38d, the recorded runs that passed through it, and its page in the explorer.

        Index File it

        Ingestion jobsA durable queue in the database. Workers claim jobs atomically.Source audited

        Queue state lives in PostgreSQL, so a job survives a restart. Redis is optional and only wakes workers, which also poll.

        Stalled workers are recovered, and retries back off. On the free deployment the API cannot index, so jobs wait for a separate worker.

        Limits

        • Job recovery was covered by the project's tests, not exercised in a recorded run here.

        Proof

        IndexerBrings the index in line with one commit, by blob SHA.Source audited

        Tracked files are compared with the index by Git blob SHA. New and changed files are parsed and embedded; unchanged files only move their commit pointer.

        The repository's last commit is written after everything else succeeds. A failed run leaves the previous index searchable.

        Limits

        • Source is not stored. Reading it later depends on the Git host being reachable.

        Proof

        ParsersPython's ast module, tree-sitter for seven more languages, line windows for the rest.Source audited

        Each function, method, class and module becomes a chunk. Repository code is parsed and never executed.

        Files that fall back to line windows are recorded as fallback, per chunk and per language, so they cannot pass as AST output.

        Limits

        • Ruby, PHP, Swift, Kotlin, Scala and C# have no grammar wired up and use line windows.

        Proof

        EmbeddingsPluggable backends. Vectors from different models are never compared.Source audited

        A chunk is embedded from its signature, docstring, calls and first body lines. The recorded runs here use granite-embedding-english-r2 as an int8 ONNX model on the CPU.

        The hash backend exists for offline tests. It is lexical, not semantic, and these recordings do not use it.

        Limits

        • Document embedding needs far more memory than a 512 MB host has, so production query serving and indexing run apart.

        Proof

        Call graphResolves a call only when one target is defensible.Recorded run

        A name resolves within its own file first, then through imports, then if it is unique in the repository. A wrong edge misleads an assistant; a missing one only loses recall.

        Indexing this commit resolved 6,977 calls and left 17,764 unresolved and 2,888 ambiguous.

        Limits

        • Dynamic dispatch is not followed. Most unresolved calls reach the standard library or dependencies, and the graph is deliberately incomplete.

        Proof

        Store Keep pointers

        PostgreSQL storeChunk pointers, pgvector embeddings, edges and jobs. Source stays in Git.Source audited

        An HNSW index serves dense search and a GIN index serves full-text search.

        SQLite is used in tests, with Python fallbacks over the same columns. Quality numbers are only reported for PostgreSQL.

        Limits

        • The project reports that pointing at code saves about 5% of the database, because vectors and their index dominate.

        Proof

        Serve Find, then check

        RetrieverKeyword, dense, hybrid and graph modes, with the mode used always reported.Recorded run

        Auto is dense when dense can run, and hybrid when the caller passes hints. If embeddings are unavailable it falls back to keyword and says so. An explicit mode that cannot run is refused.

        Hybrid is reciprocal rank fusion of keyword and dense, with a boost for an exact symbol name. Tests, docs and examples are down-ranked unless the question asks for them.

        Limits

        • Repository scope is a filter the caller chooses. A call that names no repository searches every repository in the index.
        • The retrieval metrics are read from project documentation. They were not reproduced for this site.

        Proof

        Source verificationCode is read at the indexed commit and compared with its Git blob SHA before it is returned.Recorded run

        PHAROS stores pointers instead of source. To answer, it fetches the file at the pinned commit, hashes the whole file the way Git does and compares that with the SHA recorded at index time.

        A mismatch withholds the code and reports why. Cached bytes pass through the same comparison.

        Limits

        • This proves the bytes match the indexed commit. It says nothing about whether the code is correct or secure.
        • With no SHA on record, source is still returned, marked unverified. Files PHAROS indexes get a SHA; the check depends on that row.

        Proof

        Context assemblyRanked code, neighbours and rules, rendered with citations inside a budget.Recorded run

        The same call serves REST, MCP and the CLI. It returns structured chunks and a Markdown rendering with path and line citations.

        The response records whether the budget truncated it.

        Limits

        • Character budgets are approximate token budgets.

        Proof

        Repository memoryLearned conventions and history. It failed its primary evaluation.Failed its gate

        Memory is mined from the index and Git history and added to the context after ranking, so it cannot change what retrieval returns.

        The locked evaluation failed its primary recall gate and its precision gate. Repository Q&A improved, but that was a secondary measure.

        Limits

        • Memory was not learned for the index behind these recordings, so it does not appear in them.

        Proof

        Interface Hand it over

        MCP serverEight read-only tools over streamable HTTP.Recorded run

        Assistants connect directly. Every tool is read-only and returns what the REST API returns.

        The recorded handshake listed retrieve_context, search_code, find_symbol, list_repositories, get_repo_brief, search_memory, list_skills and get_skill.

        Limits

        • Authentication is static bearer tokens. There are no user accounts.

        Proof

        REST APIThe same operations under /api/v1, with admin and read scopes.Recorded run

        The read token can search and fetch context. It cannot index, delete or reach admin endpoints.

        Older routers for papers, planning and a resource graph are still mounted and maintained to a lower bar. This explorer covers the code-intelligence path only.

        Limits

        • No public endpoint is called from this site.

        Proof

        The check itselfbackend/app/codeintel/source.pyOpen source

        The function every cited span passes through, exactly as it reads at the indexed commit. It loads the file, hashes it the way Git does, and withholds the code when the hash differs from the one recorded at index time.

        Mode
        pinned source
        Commit
        975a38d
        Lines
        141–162
        Blob
        c9f05cf7bf87
        def _resolve_one(req: SourceRequest, token: str | None) -> SourceResult:    try:        data, origin = _load(req, token)    except PermissionError:        return SourceResult(req.key, "unavailable:host_not_allowed")    except FileNotFoundError:        return SourceResult(req.key, "unavailable:not_found")    except OverflowError:        return SourceResult(req.key, "unavailable:too_large")    except LookupError:        return SourceResult(req.key, "unavailable:no_raw_endpoint")    except GitError:        return SourceResult(req.key, "unavailable:git_error")    except Exception as exc:  # network errors, timeouts        logger.info("source fetch failed for %s: %s", req.path, type(exc).__name__)        return SourceResult(req.key, "unavailable:fetch_failed")    verified = False    if req.blob_sha:        if git_blob_sha(data) != req.blob_sha:            return SourceResult(req.key, "unavailable:content_mismatch")        verified = True    return SourceResult(req.key, "resolved", _slice(data, req.start_line, req.end_line), verified, origin)

        Pass 3 · Deep dive

        How did it get here?

        PHAROS didn’t start as a code-search service. It started as a much bigger idea, and most of what it is now came from finding out which parts were real.

        1. Sep–Dec 2025

          It began as Neo Alexandria

          A research library: papers, citations, annotations, recommendations, and three-way search fused by rank, planned phase by phase as requirements, design and task documents. The SPLADE retriever comes from here.

          What it taught me A plan for every phase is not proof for every phase. Its own test-fix specification recorded 74.8% of tests passing.

        2. Jan 2026

          Tests an assistant can’t rewrite

          Expected values moved into read-only golden-data files, and a failing test says not to edit the test.

          What it taught me Write the answer down before the code can see it.

        3. Feb–Apr 2026

          Renamed PHAROS, and pointed at code

          A cloud API with a separate GPU worker, AST parsing and code search, aimed at coding assistants.

          What it taught me A narrower question is easier to answer well.

        4. Apr–May 2026

          Audit the claims, including mine

          An April audit, run by an AI reviewer told to trust no documentation, found 3 of 9 components missing, stubbed or invented. A May review found search returning results with no file paths and no code.

          What it taught me Documentation is a claim, and claims need evidence.

        5. Jul 2026

          Cut back to the core

          The knowledge-management product was removed, module boundaries became a CI gate, and PHAROS began speaking real MCP.

          What it taught me Removing a feature can be the most useful change.

        6. Oct–Nov 2026

          Rebuilt around proof

          A chunk-level code index with verification at commit. Labels were hashed before any run, each locked test set was run once, and the memory protocol was fixed before memory code existed. Retrieval passed; memory failed, and the failure stays on this page.

          What it taught me Set the bar first, then publish whichever side of it you land on.

        Every milestone from April 2026 on, with its commit

        How the history is known3 claims, each with how it is known
        • PHAROS began in September 2025 as Neo Alexandria, a research-library backend for papers, citations, annotations and recommendations, specified phase by phase as Kiro requirements, design and task documents, and was renamed PHAROS in February 2026.

          ReportedLedger

          From PHAROS's commit history and specifications at 975a38d. Owner to confirm the framing of the project's origin.

        • In late 2025 the project's own test-fix specification recorded a 74.8% test pass rate, and in January 2026 a new suite moved expected values into read-only golden-data files whose failures tell the reader not to edit the test.

          ReportedLedger

          From PHAROS's own specifications and commit history. Owner to confirm that the early test record may be shown.

        • An April 2026 audit, run by an AI reviewer told to trust no documentation, found 3 of 9 audited components missing, stubbed or invented, and a May 2026 review found search returning results with no file paths and no code.

          ReportedLedger

          From two project documents at 975a38d. Owner to confirm that these earlier findings may be shown.

        Pass 3 · Deep dive

        What are its limits?

        • Retrieval quality is reported, single-annotator and not reproduced for this portfolio.
        • Blob integrity is not semantic correctness or a security certification.
        • Conservative graph resolution means the call graph is deliberately incomplete.
        • This page does not query PHAROS. It is a static case study, and the explorer's runs are recordings.
        • Repository scope is a filter the caller chooses. A call that names no repository searches the whole index.
        • The recordings ran on one local machine, not the deployed service.

        Pass 3 · Deep dive

        What would Ram test next?