Rename from introspector to emulator (fixes #89)

[chris-ricketts]

Summary

• Renames the project and public service identity from introspector to emulator across module paths, command/build metadata, Docker setup, configuration, generated API packages, docs, and tests.
• Updates the protobuf namespace and gRPC service from introspector/v1 / IntrospectorService to emulator/v1 / EmulatorService, while preserving existing REST endpoint paths.
• Renames packet/domain terminology from Introspector Packet to Emulator Packet without changing packet wire encoding, packet type byte 0x01, serialization behavior, or OP_INSPECT... opcode names.
• Switches runtime configuration to the EMULATOR_ environment prefix and changes the default app data namespace to emulator.
• Regenerates protobuf, gRPC, gateway, and OpenAPI artifacts so checked-in generated code matches the renamed API surface.

[arkanaai]

🔍 Arkana Code Review — introspector → emulator rename

Reviewed full diff (965+/938-), read all changed files for context, checked cross-repo consumers.

Wire Format / Protocol Safety ✅

Confirmed safe. No changes to:

• Packet type byte 0x01
• OP_INSPECT* opcode values
• Tagged hashes (ArkScriptHash, ArkWitnessHash, ArkadeTapSighash)
• ARK magic bytes 0x41524b
• Serialization/deserialization logic
• REST endpoint paths (/v1/info, /v1/tx, etc.)
• Default port 7073

Issues Found

🔴 P0 — Breaking change with no migration: data directory
internal/config/config.go: defaultDatadir changes from AppDataDir("introspector", false) to AppDataDir("emulator", false). Existing deployments will silently lose access to their data on upgrade. Need either:

• A migration that moves/symlinks the old dir, or
• A fallback that checks the old path if the new one doesn't exist

🔴 P0 — Breaking change with no migration: env prefix
internal/config/config.go: viper.SetEnvPrefix("INTROSPECTOR") → "EMULATOR". The new test TestLoadConfigIgnoresOldEnvPrefix explicitly confirms the old prefix is rejected. Every existing deployment's env config breaks silently (defaults kick in instead of erroring). At minimum, add a startup warning if INTROSPECTOR_* vars are detected.

🔴 P0 — No companion PRs for downstream consumers
The gRPC service rename (IntrospectorService → EmulatorService, package introspector.v1 → emulator.v1) and Go module path change break at least 4 repos at compile time:

Repo	Impact
bancod	Go imports of introspector/pkg/*, Docker image ghcr.io/arklabshq/introspector, INTROSPECTOR_* env vars in test/docker-compose.yml and internal/config/config.go
fulmine	Go imports in go.mod, pkg/vhtlc/, pkg/swap/
layerzero-usdt0-arkade-demo	Go imports, Docker build context URL github.com/ArkLabsHQ/introspector.git#master, env vars, shell scripts
banco	docker-compose.introspector.yml image + env vars, package.json scripts

These repos will fail to compile/deploy the moment this merges. Companion PRs should be prepared (or at least tracked in an issue) before merging.

🟡 P1 — buf.Dockerfile: duplicate install + sneaked Go version bump

-FROM golang:1.24-alpine3.20 AS builder
+FROM golang:1.25-alpine AS builder
 RUN apk add --no-cache git
+RUN go install github.com/bufbuild/buf/cmd/buf@v1.55.1
 RUN go install github.com/bufbuild/buf/cmd/buf@v1.55.1

1. Go base image bumped 1.24-alpine3.20 → 1.25-alpine — unrelated to the rename, should be a separate commit or called out in the PR description.
2. buf is installed twice (duplicate RUN line). Harmless but sloppy — remove one.

🟢 P2 — Cosmetic: pkg/arkade/psbt_fields.go whitespace change
Alignment padding changed on ArkFieldPrevoutTx line. Nit, no impact.

Rename Completeness ✅

The rename itself is thorough and consistent. All type names, function names, variable names, comments, error messages, module paths, proto definitions, generated code, test files, CI workflows, and Docker configs have been updated. The OP_INSPECT* opcode names are correctly preserved (they refer to the Bitcoin introspection concept, not the project name).

Recommendation

Request changes. The rename itself is clean, but merging without addressing the data directory migration and downstream breakage is dangerous. Specifically:

1. Add a migration/fallback for the data directory path change
2. Add a startup warning (or fallback) for old INTROSPECTOR_* env vars
3. Prepare companion PRs for bancod, fulmine, layerzero-usdt0-arkade-demo, and banco — or at minimum open a tracking issue
4. Fix the duplicate buf install in buf.Dockerfile
5. Split or document the Go 1.25 bump

[arkanaai]

Follow-up review — new commit 801679b

✅ Fixed since last review

P1 buf.Dockerfile — Fixed. Go version reverted to 1.24-alpine3.20, duplicate buf install removed. Good.

🔴 Still outstanding (P0s from previous review)

The three P0 blockers remain unaddressed:

1. Data directory migration (internal/config/config.go:29) — AppDataDir("introspector", false) → AppDataDir("emulator", false). Existing deployments silently lose their data on upgrade. Needs a migration or fallback.

2. Env prefix breakage (internal/config/config.go:49) — SetEnvPrefix("INTROSPECTOR") → "EMULATOR". Every existing deployment's env config silently stops working (defaults kick in, no error). At minimum detect and warn on INTROSPECTOR_* vars at startup.

3. Downstream consumers — bancod, fulmine, layerzero-usdt0-arkade-demo, and banco all import from the old module path / use the old Docker image / set INTROSPECTOR_* env vars. They break at compile/deploy time when this merges. Need companion PRs or a tracking issue.

These should be resolved before merge. The rename itself remains clean and thorough.