openfantasymap/geomqtt

Can another program use it through a documented, machine-readable surface?

• next: [library] L4 An API reference is generated from the code (autodoc, mkdocstrings, typedoc, …). (no generated API reference)

library ladder · level 3

• ✓ L1 An importable, packaged API exists. clients/geomqtt-core/package.json npm packageclients/geomqtt-leaflet/package.json npm package
• ✓ L2 The public API is delimited (__all__, an exports map, exported identifiers). clients/geomqtt-core/package.json package entry pointclients/geomqtt-leaflet/package.json package entry point
• ✓ L3 The public API is statically typed (py.typed, type declarations, a typed language). clients/geomqtt-core/package.json TypeScript typesclients/geomqtt-leaflet/package.json TypeScript types
• ✗ L4 An API reference is generated from the code (autodoc, mkdocstrings, typedoc, …). no generated API reference

service ladder · level 4

• ✓ L1 A network surface exists: HTTP routes, an MCP server, or a standard protocol listener. crates/geomqtt-server/src/http.rs rust-axum/actix: 6 route declarationscrates/geomqtt-server/Cargo.toml RESP (Redis wire protocol)
• ✓ L2 A contract exists: a checked-in OpenAPI/GraphQL/protobuf/AsyncAPI spec, a framework-generated spec, MCP tool schemas, or a standard application protocol that off-the-shelf clients speak (RESP, MQTT, gRPC, PostgreSQL wire, …). crates/geomqtt-server/Cargo.toml RESP (Redis wire protocol)crates/geomqtt-server/Cargo.toml MQTT broker
• ✓ L3 A contract covers its transport: an HTTP contract covers at least 80% of declared routes (generated contracts do), or the application layer over a standard protocol (commands, topics, payloads) is specified in a protocol document or AsyncAPI. crates/geomqtt-server/Cargo.toml RESP (Redis wire protocol)PROTOCOL.md protocol specification
• ✓ L4 A second surface: another transport (HTTP and a protocol, two protocols), an MCP server, a CLI with JSON output, or an SDK. crates/geomqtt-server/src/http.rs HTTPclients/README.md SDK

Can integrators rely on it not changing under them?

• next: L2 A changelog exists and marks breaking changes. (no changelog)

all ladder · level 1

• ✓ L1 Releases are versioned (semver tags or versioned changelog sections). 8 semver tags, latest v0.4.0
• ✗ L2 A changelog exists and marks breaking changes. no changelog
• ✗ L3 A deprecation mechanism is used in code (warnings, @deprecated, Deprecation/Sunset headers) or the API is versioned. no deprecation mechanism or API versioning
• ✓ L4 Across tagged releases, no OpenAPI operation, CLI option or __all__ symbol was removed without first being deprecated. 8 tagged releases compared

Can others react to state changes without polling?

• next: L4 Events are described by AsyncAPI or CloudEvents. (no AsyncAPI or CloudEvents contract)

service ladder · level 3

• ✓ L1 Internal events exist (signals, queues, an outbox, emitters). clients/geomqtt-core/src/client.ts 16 matchesclients/geomqtt-leaflet/src/index.ts 1 match
• ✓ L2 Webhooks sent by this system, or a streaming endpoint (SSE, WebSocket). clients/geomqtt-unreal/Source/Geomqtt/Private/GeomqttClient.cpp 24 matchesclients/geomqtt-unreal/Source/Geomqtt/Public/GeomqttClient.h 3 matches
• ✓ L3 Signed webhooks registrable through the API, or two mechanisms (webhooks, streams, a broker). clients/geomqtt-unreal/Source/Geomqtt/Private/GeomqttClient.cpp 24 matchesbench/requirements.txt 1 match
• ✗ L4 Events are described by AsyncAPI or CloudEvents. no AsyncAPI or CloudEvents contract

Can a machine act with its own revocable, least-privilege identity?

• next: L1 Programmatic authentication (bearer tokens, API keys). (no token auth)

service ladder · level 0

• ✗ L1 Programmatic authentication (bearer tokens, API keys). no token auth
• ✗ L2 Per-client, revocable credentials (managed API keys, service accounts) or OAuth2. no managed keys or OAuth
• ✗ L3 Credentials carry scopes or permissions. no scopes or permissions
• ✗ L4 Standard provisioning or federation (OIDC client credentials, SCIM). no OIDC client credentials or SCIM

Can its data get in and out, in bulk, in open formats, with an explicit schema?

Can an automated caller use it without guessing, and recover from failure?

• next: [service] L2 Field-level validation errors, and paginated lists. (no request validation)
• next: [library] L1 Errors are specific exception types, and library code never calls sys.exit. (no exception classes)

library ladder · level 0

• ✗ L1 Errors are specific exception types, and library code never calls sys.exit. no exception classes
• ✓ L2 Inputs are validated with messages naming the bad argument. clients/geomqtt-core/src/config.ts 1 match
• ✗ L3 Timeouts and retries are configurable. no timeout parameter
• ✗ L4 Agent docs, and examples that run as tests (doctests). examples don't run as tests

service ladder · level 1

• ✓ L1 Errors are machine-readable: consistent JSON over HTTP, or a standard protocol's native error replies (RESP errors, MQTT reason codes, gRPC status, SQLSTATE). crates/geomqtt-server/src/resp.rs native protocol error repliescrates/geomqtt-server/src/mqtt.rs native protocol error replies
• ✗ L2 Field-level validation errors, and paginated lists. no request validation
• ✗ L3 Typed errors (RFC 9457 over HTTP, or a standard protocol's typed error codes), idempotent writes (Idempotency-Key), and rate-limit signals. no idempotency keys
• ✗ L4 Dry-run or validate-only, conditional requests, and agent docs. no dry-run

Can another system run and compose it without a human?

• next: [library] L4 Optional features behind extras/features. (no optional extras)

library ladder · level 3

• ✓ L1 Importable from source. clients/geomqtt-core/package.json npm packageclients/geomqtt-leaflet/package.json npm package
• ✓ L2 Installable as a package (a package manifest). clients/geomqtt-core/package.json package manifestclients/geomqtt-leaflet/package.json package manifest
• ✓ L3 Published to a public registry, with at most 10 runtime dependencies. .github/workflows/npm.yml 1 match.github/workflows/release.yml 1 match
• ✗ L4 Optional features behind extras/features. no optional extras

service ladder · level 4

• ✓ L1 Runnable from source with documented steps (a README with commands). README.md
• ✓ L2 Configured through environment variables, documented: a .env example, a config schema, or docs naming at least half of the variables the code reads. crates/geomqtt-server/src/config.rs 1 match 13 of 13 environment variables named in the docs
• ✓ L3 A container image. Dockerfilebench/Dockerfile
• ✓ L4 Composition artifacts (compose, Helm, IaC). bench/docker-compose.bench.ymlbench/docker-compose.multinode-10.yml

Can behaviour be added without modifying the code?

• next: L1 Internal seams: a registry, registration function or plugin manager. (no registry or registration function)

all ladder · level 0

• ✗ L1 Internal seams: a registry, registration function or plugin manager. no registry or registration function
• ✗ L2 The docs show how to add behaviour through those seams (even in-tree). no registration functions to document
• ✗ L3 Out-of-tree extensions are discovered (entry points, a plugin directory, configuration) without editing the package. extensions must be added inside the package
• ✗ L4 The extension API is versioned, has lifecycle hooks, and has example extensions. the extension API isn't versioned

Can an operator, or an orchestrating agent, tell whether it works and why not?

• next: [service] L2 Structured logs. (no structured logging)
• next: [library] L1 Logs through a standard logger namespace and never prints from library code. (no standard logger)

library ladder · level 0

• ✗ L1 Logs through a standard logger namespace and never prints from library code. no standard logger
• ✗ L2 Log levels are used meaningfully (at least two levels). fewer than two log levels used
• ✗ L3 Optional metrics or tracing hooks. no metrics or tracing hooks
• ✗ L4 OpenTelemetry instrumentation available. no OpenTelemetry instrumentation

service ladder · level 1

• ✓ L1 A health or readiness endpoint, or a container healthcheck. crates/geomqtt-server/src/http.rs 1 matchbench/docker-compose.bench.yml 2 matches
• ✗ L2 Structured logs. no structured logging
• ✗ L3 Metrics. no metrics
• ✗ L4 Distributed tracing (OpenTelemetry). no tracing

Can an agent change it safely with limited context?

• next: L3 At least 90% of modules fit 32k tokens and no file exceeds 12k; test/source token ratio at least 0.3; at least 70% of the code is typed. (test/source token ratio 0.09 < 0.3)

all ladder · level 2

• ✓ L1 A README and some tests. README.mdclients/geomqtt-core/tests/coord.test.ts 3 test files
• ✓ L2 CI runs the tests; applications pin dependencies (libraries and zero-dependency projects are exempt). .github/workflows/ci.yml.github/workflows/npm.yml
• ✗ L3 At least 90% of modules fit 32k tokens and no file exceeds 12k; test/source token ratio at least 0.3; at least 70% of the code is typed. test/source token ratio 0.09 < 0.3
• ✓ L4 No import cycles, and agent docs (AGENTS.md, CLAUDE.md, llms.txt). CLAUDE.md