Skip to content

schema: declare non-null elements on eight list positions - #244

Merged
dkijania merged 2 commits into
mainfrom
schema/non-null-list-elements
Oct 7, 2026
Merged

dkijania merged 2 commits into
mainfrom
schema/non-null-list-elements

Conversation

@dkijania

@dkijania dkijania commented Oct 7, 2026

Copy link
Copy Markdown
Contributor

Closes #236.

Eight list positions go from [T]! to [T!]! (eventData/actionData: element only, the field stays nullable). No resolver produces a null element; see #236 for the per-position evidence.

  • graphql-inspector: 8 changes, no breaking change.
  • tests/unit/schema-nullability.test.ts: every output list must declare non-null elements, except ZkappFieldArray.fields. Fails on main with exactly these eight, passes here.
  • Unit 216/216, integration 91/91 (Node 24, PostgreSQL 17); no Cannot return null in any response.

Lets the three SDKs keep non-null element types in their 2.0 instead of widening them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01StPY7C6STPhukrgZvVhqZX

@SanabriaRusso SanabriaRusso left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving. All eight positions are output-only, so nothing changes on the wire for o1js, mina-explorer or the client SDKs, and no input type or argument is touched.

What I verified

  • graphql-inspector@7.0.0 (the version CI uses), run against main: 8 changes, all safe, "No breaking changes detected".
  • No position can return a null element. I traced each one to the code that produces it:
    • Query.events, Query.actions and Query.blocks are object literals built in the services, with ?? [] defaults.
    • EventData.data / ActionData.data come from zkapp_field.field, which is text NOT NULL, through an INNER JOIN. In removeRedundantEmittedFields, .flat() drops the sparse holes.
    • zkappAccountUpdateIds comes from zkapp_account_updates_ids, which is integer[] NOT NULL.
  • The wider null spread under [Block!]! can't be reached today. Every required Block sub-field is safe:
    • creator comes from an INNER JOIN.
    • state_hash and parent_hash are NOT NULL.
    • coinbase and amount are COALESCEd.
    • A bad timestamp already failed the whole query before this PR.
  • Codegen. npm run codegen reproduces src/resolvers-types.ts exactly.
  • Tests.
    • Unit tests: 216/216.
    • Integration tests: 91/91 on Postgres 17.
    • Live GraphQL queries for events, actions and blocks(limit: 500) against the fixture DB returned data with no "Cannot return null" errors.
  • CI. All checks pass.

Optional

  • Null spread note. Issue #236 asked for one sentence in the description about the wider null spread for blocks: a future computed field that throws would null the whole result. Worth adding so the note reaches the squash commit.
  • SCHEMA_VERSION. It stays 1.1 here. #245 moves it to 2.0 on top of this PR, so no bump is needed in this PR.

@dkijania
dkijania merged commit 22dc8d4 into main Oct 7, 2026
12 checks passed
@dkijania
dkijania deleted the schema/non-null-list-elements branch October 7, 2026 15:48
dkijania added a commit that referenced this pull request Oct 9, 2026
Release 2.0.0: an **alignment major**. No breaking change against 1.0.0.

## Why 2.0.0 and not 1.1.0

By the rules in `docs/versioning.md`, the changes since `v1.0.0` would
be a minor. We take a major anyway, for these reasons:

1. **The SDKs need 2.0.** mina-archive-sdk-js/go/rust have breaking
changes to their own API since their 1.0.x releases. Examples: Rust
`#[non_exhaustive]` on all output structs, new `Error` variants and
`i32` builders; Go `DateTimeGte`/`DateTimeLt` as `*time.Time`. These
changes are what make future server minors non-breaking for SDK users,
so we do not revert them.
2. **One rule instead of a lookup table.** If the versions are not
aligned, users must remember that "SDK 2.x works with server 1.1". With
one shared major, the rule is: **same major means compatible**. A higher
server minor only adds features that the SDK does not wrap yet.
3. **Semver allows it.** Semver forbids a breaking change without a
major. It does not forbid a major without a breaking change. The only
cost is one upgrade decision for operators, and the upgrade notes cover
it.
4. **The cost is low now.** npm never received 1.0.x (it has only
`0.0.6`), so npm users see `0.0.6` → `2.0.0`. `schemaVersion` never
shipped in a tag. The Go SDK module path is already `/v2`.

## Changes

- `package.json` 2.0.0, `SCHEMA_VERSION` "2.0".
- `docs/versioning.md`:
  - "One major across the server and the SDKs";
  - MAJOR now also covers an alignment major;
  - "Upgrading to 2.0.0" (from `0.0.6` and from 1.0.0);
  - tag-based releases (do not run `npm version` on `main`).
- `docs/runbook.md`: you can roll back to any image from 1.0.0 or later.

## Compatibility checked

- Schema 2.0 against `v1.0.0`: graphql-inspector reports only safe
changes (additive, plus output-only `[T]` → `[T!]` from #244).
- The integration suites of the published SDKs (Go `v1.0.0`, JS
`v1.0.1`, Rust `v1.0.1`) and of the SDK 2.0 branches (js#30, go#30,
rust#29) pass 5/5 against a build of this branch.

## Before tagging `v2.0.0`

- Fix npm publish auth. The `v1.0.0` publish failed with `ENEEDAUTH`
(run 33921445418).
- Merge #246 (height race in `tests/resolvers.test.ts`).
- Tag the merge commit as described in "Releasing". Then merge the SDK
PRs and tag them `v2.0.0`.

## Draft release notes

> **2.0.0 is an alignment major: no breaking change against 1.0.0.** The
server, its schema and the client SDKs now share one major version, so
the same major means compatible. See [Upgrading to
2.0.0](https://github.com/o1-labs/Archive-Node-API/blob/main/docs/versioning.md#upgrading-to-200).
npm users come from `0.0.6`, so they must read both lists.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01StPY7C6STPhukrgZvVhqZX
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

schema: tighten eight list positions to non-null elements ([T]! → [T!]!)

2 participants