ground-strike

groundstrike

groundstrike is a typed, headless Go code-indexing library. Callers provide a bounded workspace Source and a relational Store; the engine reconciles complete generations and exposes lexical search, Go-symbol outlines, and status.

The core implementation is transport-independent and contains no MCP, JSON-RPC, provider, embedding, or vector dependency. HRNS can embed that library directly. The separate mcpserver package set packages the same engine as a filesystem-backed MCP server over stateless Streamable HTTP for container deployments.

Start here

• Architecture and operations — current API contracts, generation/storage invariants, SQLite ownership and recovery, error handling, lifecycle, security, support, verification, and review-open release gates.
• Documentation index — current, roadmap, evaluation, and explicitly historical documents.

The prior embedding-sitter handoff was removed during this swap and is not part of the current implementation plan.

Packages

• groundstrike: minimal typed API and bounded reconciliation engine.
• groundstrike/sqliteindex: relational SQLite/FTS5 generation store.
• groundstrike/internal/*: cohesive chunking, Go-symbol, planning, and query helpers that are not part of the caller contract.
• mcpserver: filesystem source, MCP Streamable HTTP adapter, and runnable server command within the repository's single Go module.

SQLite data is derived and crash-safe: a generation becomes visible only after its files, chunks, symbols, and FTS rows commit atomically. An exact matching ready/fresh snapshot digest reuses the active generation without reading files or writing a replacement. On Darwin and Linux, one store owns a process-lifetime, nonblocking advisory lock at <index.db>.writer.lock; contention returns groundstrike.ErrWriterOwned.

Minimal wiring

store, err := sqliteindex.Open(ctx, dbPath, sqliteindex.Options{
    RecoverCorrupt: true,
})
if err != nil {
    return err
}
defer store.Close()

engine, err := groundstrike.New(groundstrike.Options{
    RootID: "workspace-stable-id",
    Source: boundedSource, // implemented by the embedding application
    Store:  store,
})
if err != nil {
    return err
}

report, err := engine.Reconcile(ctx)

See Architecture and operations for a complete ownership example and error-classification guidance.

Requirements and support

• Go version declared by go.mod: 1.25.12.
• SQLite 3.51.3+ with FTS5, supplied through modernc.org/sqlite.
• sqliteindex writer ownership: Darwin and Linux on a private local filesystem. Other operating systems are currently unsupported.

Docker MCP server

The stable container will serve MCP Streamable HTTP at /mcp and health checks at /healthz. Mount the indexed workspace read-only and keep the derived SQLite state in a separate volume:

docker run --rm \
  -p 127.0.0.1:8080:8080 \
  -v "$PWD:/workspace:ro" \
  -v ground-strike-data:/data \
  docker.io/florasync/ground-strike:${GROUND_STRIKE_IMAGE:-v0.0.1}

Configure clients with http://127.0.0.1:8080/mcp. The server exposes reconcile, search, outline, and status. It has no application-layer authentication, so do not publish its port on an untrusted network without an authenticating reverse proxy. v0.0.1-alpha.1 is source-only and does not publish an image. Docker Hub publication begins with stable v0.0.1; tag-backed CI publishes docker.io/florasync/ground-strike from the protected release environment.

Development

make build
make test
make race
make vet
make check-code-index-coverage
make bench

make check runs tests, vet, and coverage. The checked-in code-index-coverage.manifest defines every feature-owned production file; the coverage gate fails if a listed package or the aggregate is below 90.0%.

Downstream HRNS compatibility and production-shaped qualification are release gates, not evidence carried by this repository. The alpha candidate is verified against a concrete HRNS checkout before tagging; any retained downstream results must remain in that repository or a linked immutable evidence artifact. Open performance and module-release gates remain listed in Remaining review-open gates.