P2: Declare 1.0.0 + versioning & schema stability policy (#178)

[dkijania]

What & why

Part of the production-readiness epic (#163). Closes #178.

The package was pre-1.0 (0.0.6) with no documented stability guarantees — public consumers need them.

Changes

• Bump to 1.0.0 in package.json.
• docs/versioning.md — SemVer applied to the GraphQL schema / HTTP endpoints / config: a precise definition of breaking vs additive changes, a deprecation policy (@deprecated + one minor & 90 days before removal), and how the existing graphql-inspector "Check Schema" gate enforces it via the expected-breaking-change label.
• Linked the policy from the README.

Important: this PR does not publish anything

The version bump is package.json-only — no git tag, so no release is cut. Publishing is tag-triggered (npm version + git push --follow-tags) and remains a deliberate maintainer action. Treat merging this PR as the decision to declare 1.0; if you're not ready for that, hold the PR (the policy doc stands on its own). Sequence it after the other production-readiness PRs so 1.0.0 ships with them.

Testing

Docs + version only. prettier --debug-check . clean; build sane. No code changed.

🤖 Generated with Claude Code

[SanabriaRusso]

Thanks for pinning this down — a written stability contract is exactly what public consumers (the mina-explorer, o1js) need before 1.0, and the graphql-inspector "Check Schema" tie-in is a great enforcement hook.

One high-value addition: the policy defines what is breaking and how to deprecate, but doesn't codify the practice this repo already relies on to protect existing clients — shipping backward-incompatible query/response changes OFF by default behind an env flag. We already do this with ENABLE_BLOCK_TRANSACTION_DETAILS (src/server/server.ts, default off — gates block-detail / parentHash output) and ENABLED_QUERIES (src/resolvers.ts — allowlists exposed queries). That's what lets the Explorer survive changes: it fires fallback query chains and degrades on the exact "Cannot query field" validation error, so any change to default response shape or exposed fields must be opt-in, or it silently blanks Explorer pages. Codifying it makes it a rule rather than a convention:

### Flag-gating behavior changes
Changes that alter default response shape/content or exposed query surface ship disabled by default behind an environment flag (e.g. ENABLE_BLOCK_TRANSACTION_DETAILS, ENABLED_QUERIES). This keeps existing clients — notably the mina-explorer, which relies on stable default responses and "Cannot query field" fallbacks — working after upgrade. A flagged, default-off change is minor; flipping such a default (or removing the flag) to change out-of-the-box behavior is major.

Two small doc nits while you're in here:

1. The endpoint list references /readiness and /metrics, which arrive via P1: Add readiness probe distinct from liveness (#169) #187 and P1: Expose Prometheus metrics at /metrics (#173) #191 — worth a note to reconcile at merge, since 1.0 ships after them.
2. For output fields the breaking direction is non-null → nullable (nullable → non-null is safe); the current "nullable → non-null" wording is right for arguments/inputs but reversed for output fields. graphql-inspector classifies these correctly regardless, but since this doc's job is to define "breaking" precisely, the prose is worth matching.

[dkijania]

Thanks @SanabriaRusso — both done in 30863c7.

Flag-gating policy. Added as its own section, close to your wording. I kept your reasoning about why rather than just the rule, because it's the part that makes it stick: the schema checker structurally cannot catch this. An unflagged change to a default response isn't schema-breaking — nothing errors, "Check Schema" stays green, health checks stay green, and the Explorer just blanks pages. A convention that only holds when someone remembers it is exactly the thing worth writing down.

Verified both cited flags exist as described before codifying them: ENABLE_BLOCK_TRANSACTION_DETAILS (src/server/server.ts:11) and ENABLED_QUERIES (src/resolvers.ts:61).

Nullability direction. Fixed, and split by position rather than patched, since the two are genuine mirror images:

• Output fields: breaking is String! → String — clients may now receive null. The reverse only strengthens the guarantee.
• Arguments/inputs: breaking is String → String! — it rejects callers that legitimately omitted it. The reverse is safe.

The old single line was right for arguments and backwards for fields. Since this doc's whole job is to define "breaking" precisely, stating one rule and applying it to both positions was the bug.

On /readiness and /metrics — no change needed here: the merge plan puts this in wave 4, after #187 and #191, so they'll exist by the time 1.0 ships. Flagging that this doc and #197's runbook now both anchor on 1.0.0 as the version where those endpoints appear, so they agree.