# Gecko

> The knowledge graph for APIs your agent can trust. Open-source, runs on your machine.
> One command maps any API — even the messy, paywalled, or on-chain ones — into a
> verified graph your agent traverses instead of guessing. Every action can be simulated
> to a receipt before money moves, and every failure shows exactly why. Built for the
> calls your agent must not get wrong.

Gecko is NOT the agent and NOT an orchestrator. It is the memory-and-context substrate
under other people's agents: it comprehends external surfaces (REST APIs and Solana
programs), projects them as first-call-correct tools over MCP, verifies actions by
simulation before execution, and never signs, never broadcasts, never stores payloads
(control-plane invariant: surfaces + correctness metadata only).

## Architecture — the three views

- [Context engineering](docs/architecture.md#context-engineering): semantic memory =
  comprehension + a lexical token-overlap catalog — deterministic retrieval; BM25 and
  vector tiers both sit behind evidence gates (flipped only on measured recall failure),
  fed by a misrank-aware retrieval eval (golden set + closed miss-cause
  vocabulary); procedural memory = question-shaped tool defs (auth stripped)
  + typed executable plans (landing_plan, dependency-ordered derivation); episodic memory
  = a categorical corpus (closed vocabularies, never payloads) + an N-confirmed drift
  series, self-generated by re-simulation; working memory = just-in-time projection —
  scale-adaptive tool listing (full defs withheld above scale, recovered per-tool on
  demand) and measured context cuts (−77%/−89% on two real specs; bytes measured,
  tokens estimated).
- [Full pipeline](docs/architecture.md#pipeline): untrusted sources (OpenAPI, docs,
  Anchor IDLs, program source, the Orquestra catalog) → anti-poison gate (sanitize,
  quarantine, Skill Guard) → comprehension (ingest, PDA seed recovery, auto-comprehend
  with measured overlays) → provenance knowledge graphs (every edge tagged EXTRACTED /
  RECOVERED / FLAGGED; API side: EXTRACTED / DECLARED / INFERRED / CLAIMED→VERIFIED /
  REFUTED) → projection (MCP hosted + stdio, CLI, Scorecard, Playground) → the verify
  path: plan → external builder (Orquestra /build) → simulate → Receipt → signing gate →
  external signer (wallet / TEE / human).
- [The proven on-chain loop](docs/receipt.md): intent → derive the full account set
  (including accounts the IDL hides) → control-plane state reads for sane args → external
  build → unsigned prelude assembly (ATA-idempotent + compute budget, for simulation
  only) → simulateTransaction on a $0 mainnet fork → a Receipt (status, categorical
  revert class, compute units) → only a passing receipt reaches the signer.

## What WORKS today (proven, live)

- find_start: intent → the right (program, instruction) start point — ranked, with a
  dependency-ordered derive plan, provenance on every account (extracted / recovered /
  flagged), declared preludes, and an honest no-start below the retrieval floor.

- Comprehension of any OpenAPI/docs surface into question-shaped tools; auth invisible to
  the agent, injected at call time. 14+ real specs validated; 0 expose an auth header.
- PDA seed recovery from Anchor IDLs AND program source (Steel/no-IDL proven on ORE) —
  including recipes the IDL structurally drops (Anchor #4057) or hides (accounts that
  travel only as remaining_accounts).
- Auto-comprehend-on-pick: point at an Orquestra project → a generated program config,
  differential-proven equal to hand-authored ground truth on 4 programs, with an explicit
  measured overlay of what could NOT be derived from any public surface.
- The simulate→Receipt engine, live-proven five times: a Pump.fun buy where the naive
  path reverts (AnchorError 3012) and Gecko's landing bundle passes (86,669 CU), a
  Meteora DLMM swap (wrap → swap across live bins → unwrap, 81,964 CU), a MetaDAO
  launchpad fund on a currently-Live launch (44,476 CU) — a program whose IDL carries
  ZERO PDA seeds and whose USDC vault exists only as a field inside the launch account —
  an ORE claim (41,023 CU) where the BUILDER'S OWN instruction fails: its Steel IDL
  marks `board` read-only, the program hands it to a closing self-CPI as a writable
  signer, so the naive bundle transfers the tokens and then dies on "writable privilege
  escalated"; Gecko reconciles the meta from source and it lands — and a Pump.fun sell
  (50,783 CU) whose whole shape lives in PROSE: the IDL and the builder both list 14
  accounts, the real instruction is 16 (or 17 for a cashback coin, a state read), and the
  naive bundle transfers the tokens and then reverts 6074 InvalidBondingCurveV2 on an
  account named only in an English doc-comment. All at $0, on a mainnet fork, before any
  spend.
- Real recovered facts a coding agent cannot get from the surface: Meteora's base_factor
  4th seed (the deprecated 3-seed scheme silently derives the WRONG pool), Pump.fun's
  bonding_curve_v2 (required, invisible in the IDL), the fee-recipient field resolved
  empirically by a refuting Receipt, the liquidity-bitmap bin-array walk (the naive
  heuristic fabricates dead accounts).
- The categorical corpus (observed / reported / synthetic / simulated tiers) + the
  N-confirmed drift detector; values-free by construction (audited). The simulated
  tier is wired end-to-end: the landing orchestrators and the `simulate` tool take an
  explicit `record_to` opt-in (default: record nothing) and `gecko drift` reads the
  series back — categorical rows only, never a pubkey/amount/log.
- Anti-poisoning: sanitizer, per-tool quarantine, image Skill Guard (rendered-pixel
  payloads, encoded-content rescan), SSRF netguard, out-of-band auth-host anchoring,
  fail-closed signing gate. An AST-enforced boundary proves the landing layer contains
  no sign/send path.
- Cross-API correlation on DECLARED value-domain joins (proven Pegana × Birdeye ×
  Jupiter); context compression −77/−89% with first-call-correctness held.

## NOT built yet (honest)

- The drift scheduler (re-simulation on cadence; today the series accrues only when runs
  happen). Hosted point-and-simulate. Hosted program surfaces beyond the first.
- The signing gate binding to the exact simulated message hash (evaluate_tx), and the
  TEE credential backend. Today's gate is verdict-based (the diagram labels this honestly).
- Catalog breadth: 4,500 projects listed, 4 wired deep. Non-Anchor generalization is
  proven once (ORE); wider Steel/native coverage is open.
- ORE `mine` (needs an off-chain drillx PoW solver — out of scope by decision) and ORE
  `checkpoint` (claim's precondition; its surface account set is short by two — declared,
  not wired). Pump.fun `sell` is now WIRED and live-proven, so the round-trip
  (buy → sell) is complete on that program; all four target programs have at least one
  runnable executable intent (pump buy + sell, meteora swap, metadao fund, ore claim).
  Pump's mayhem-mode coins are FLAGGED, not claimed: the one mainnet mayhem sell
  inspected did not use the standard `bonding_curve_v2` derivation.
- The semantic/vector retrieval tier (deliberately OFF behind an evidence gate — flips
  only on measured lexical recall failure, not fashion).
- Cross-customer episodic pooling (tenancy is local-only until a consent/egress layer
  exists). Live x402 billing (stub by design).

## Optional

- [Receipt semantics](docs/receipt.md): what a Receipt asserts (lands vs a snapshot,
  categorical revert class, compute units) and what it deliberately does NOT (price
  prediction, mainnet finality).
- [Trust boundary](docs/trust-boundary.md): why an agent executing untrusted context
  while holding credentials is one disease, and how comprehension-native security
  differs from a firewall.
- [Program-flow gap map](docs/specs/2026-08-04-orquestra-program-flow-gap-map.md):
  the measured gaps between "accounts derived" and "transaction lands".
