Split subgraph on deployment facts, not wholesale: manifest as a template in the lib repo, networks.json in the deploy repo

[thedavidmeister]

rainlanguage/rain.metadata.deploy#4 and #148 move the whole
subgraph/ directory — all 15 files — out of the library repo. That cut costs the
schema drift guard and it is not the cut the tooling wants.

The cut this issue proposes

Split on whether a file carries deployment facts, not on "the subgraph".

Stays in rain.metadata — subgraph.yaml (as a template, see below), schema.graphql,
src/metaBoard.ts, src/transaction.ts, tests/*, package.json,
docker-compose.yml. This is subgraph SOURCE. The repo runs graph codegen and
graph test and never graph build --network.

Moves to rain.metadata.deploy — networks.json, the Goldsky deploy workflow, and
the deploy-record test. At deploy time the workflow checks out the library repo's
subgraph source into a temp dir, drops networks.json beside it, runs
graph build --network <x> there, and deploys. The manifest mutation lands in the temp
copy and is never committed.

That direction is deploy → library, which the split allows. The current PRs need the
library's interface artifact path repointed at the deploy repo's concrete precisely
because they move the manifest the wrong way.

The template

subgraph.yaml's source: block keeps only abi: MetaBoard. No address, no
startBlock.

Measured, do not re-derive

Run on rain.metadata@main in the pinned rainix shell, baseline vs stub, both after
forge soldeer install:

• The stub builds. With address and startBlock deleted from subgraph.yaml,
  subgraph-build completes for all five networks, exit 0, and the built manifest at
  subgraph/build/subgraph.yaml carries the real matic address. graph build --network
  fills both from networks.json.
• graph codegen does not need them. It ran and printed "Types generated
  successfully" on the stubbed manifest before any graph build had filled anything.
• graph build --network writes back into the SOURCE subgraph.yaml, not only
  build/. After the run the stub's own committed manifest carried both fields again.
  A stub does not stay stubbed in a tree that runs build.

That last point is why the template only works if the library repo never runs
graph build --network, and it is also a live latent bug today:

• subgraph_networks iterates jq keys, so the order is alphabetical —
  arbitrum-one, base, base-sepolia, flare, matic.
• Whichever network sorts LAST is what subgraph.yaml holds after every build.
• matic sorts last today and matic is what is committed, so git status is clean by
  coincidence. Add a network sorting after matic and every subgraph-build leaves a
  dirty tree, and nothing checks.

So the committed inline address/startBlock are not a template default. They are a
residue of the last build. The template removes the residue rather than documenting it.

What this recovers

schema.graphql stays in the same tree as crates/metaboard/src/schema/metaboard.graphql,
so the consumer-snapshot drift check is local and per-PR: regenerate the snapshot from
the schema and git diff --exit-code, the same shape as rainix-copy-artifacts. No
token, no introspection, no cross-repo fetch.

That also replaces crates/cli/src/cli/schema_check.rs (948 lines of bespoke GraphQL
comparison) with a generator plus a diff. The snapshot is the entity-type projection of
schema.graphql, which is what schema_check's own check() already compares, so it is
derivable rather than hand-written.

Why this matters to consumers: cynic's build.rs registers the schema from the local
snapshot and checks the QueryFragment derives against THAT file at compile time. Drift
is invisible to the compiler — the crate builds against a stale snapshot, sends the
query, and the live subgraph rejects it at runtime as CynicClientError::GraphqlError,
surfacing through FetchAuthoringMetaV2WordError, which raindex propagates in its own
error enum. The queried surface is metaV1S(where: {metaHash|subject}) →
metaHash, meta, sender, id, metaBoard { address }, subject and
metaBoards(first, skip) → address. Rename or retype any of those and every consumer's
meta fetch fails; adding fields breaks nothing.

Two verifications this work must run

1. Matchstick on a stubbed manifest. graph test mocks chain state rather than
   connecting, so it should not need the address, but the repo's tests currently run
   against a full manifest and this was not testable locally (no docker). If graph test
   needs the address, say so and propose the alternative rather than putting the address
   back silently.
2. network: in the template. The stub above kept network: matic hardcoded and the
   build passed because --network overrides it. Leaving a real network name in a
   template is the same misleading residue one level up. Test whether graph accepts a
   placeholder; if it does not, record why the name has to stay.

Consequences for the open PRs

Both #4 and #148 need reworking rather than amending — instead of moving 15 files out,
move one file plus two workflows.

Four of #4's five assertions survive in the deploy repo unchanged, because they work off
networks.json plus the deploy records: every frozen release indexed on every network,
one address per datasource across networks, every indexed network covered by
supportedNetworks(). networks.json carries the datasource names and addresses itself,
so no manifest is needed for those.

The fifth — the manifest's ABI path derived from the deploy candidate's artifactPath —
moves to rain.metadata and becomes a pin against the interface, alongside the
MetaV1_2 event-signature pin that is already manifest-vs-interface.

Out of scope, stated so it is not mistaken for fixed

Three MetaBoard addresses are in play and nothing reconciles them under any cut:
networks.json says 0xfb8437Ae…, src/generated/candidate/MetaBoard.sol says
0x8fD50fF9…, and the one live subgraph indexes 0x59401c93… under the name
metadata-base, not metaboard-*. Separate work.

subgraph-deploy remains unexercisable without CI_GOLDSKY_TOKEN.

[thedavidmeister]

Correction to the "What this recovers" section, found while implementing this.

The issue says the consumer snapshot is "the entity-type projection of `schema.graphql`". That is wrong. `crates/metaboard/src/schema/metaboard.graphql` is the full graph-node API schema, not an entity projection — cynic's derives in `crates/metaboard/src/types/metas.rs` need `Query.metaV1S(where: MetaV1_filter)` and `Query.metaBoards(first, skip)`, and an entity-only projection would not compile.

So a faithful generator means reimplementing graph-node's API-schema derivation: the `_filter` inputs, `_orderBy` enums, the `Query`/`Subscription` roots, `_change_block`, and `derivedFrom` argument expansion. That is its own PR with real design risk, and a subtly wrong generator is worse than the status quo.

The regenerate-and-diff shape is still the right target; it is just not the cheap extraction this issue implied. Splitting it out as a follow-up rather than folding it into the split PRs.

Both verifications the issue asked for came back positive:

1. Matchstick passes on a stubbed manifest — CI run 32504106539, "All 10 tests passed!", container exit 0, with no `address`/`startBlock` in `subgraph.yaml`. `graph test` does not need the address.
2. `network: template` is accepted — `graph codegen` exit 0, and `graph build --network ` exit 0 for all five networks from the placeholder, with the built manifest carrying the correct network, address and startBlock each time. `--network` overrides the name too. And `graph build --network` with no `networks.json` fails loudly (`Error: Network file 'networks.json' does not exists`, rc=1), so the library tree cannot silently do a network build.

[thedavidmeister]

Checked against main at 6fe2e2bfcefaf49096c87260828a6d8330df7a3b. The cut this issue proposes is already on main — #148 (merge bba50a7, an ancestor of main) landed the library half and rainlanguage/rain.metadata.deploy#4 landed the deploy half. Neither PR carried a closing keyword, which is the only reason this is still open. No PR opened; there is nothing left to change for the cut itself.

Evidence, read off main rather than off the PR prose:

The template. subgraph/subgraph.yaml's data source is exactly:

    name: metaboard0
    network: template
    source:
      abi: MetaBoard

No address, no startBlock, and network: is the placeholder — the issue's "The template" section verbatim, plus the network: the issue's second verification asked about.

Stays / moves. subgraph/ on main holds subgraph.yaml, schema.graphql, src/metaBoard.ts, src/transaction.ts, tests/*, package.json, package-lock.json, docker-compose.yml — the "stays" list. subgraph/networks.json and .github/workflows/manual-subgraph-deploy.yml are absent here and present in rain.metadata.deploy, whose subgraph/ contains networks.json and nothing else. That workflow does the fetch-into-a-temp-tree the issue described: it checks out rainlanguage/rain.metadata at a ref into .subgraph-source, copies subgraph/ over its own, and hard-fails if the library ships a networks.json ("rain.metadata ships a networks.json; it would shadow this repo's deploy record"), so the direction stays deploy → library and the shadow case is asserted rather than assumed.

The write-back bug. MetaBoard Subgraph CI runs graph codegen + subgraph-test, never subgraph-build, with the reason inline in the workflow. test/subgraph/SubgraphManifest.t.sol::testManifestSourceCarriesNoDeploymentFact then makes the residue non-silent: yq over parsed YAML rejects any address/startBlock key document-wide and pins every network: to the placeholder, so a graph build --network run in this tree fails a test instead of being committed by the next git add -A. CLAUDE.md carries the same rule under "The subgraph is SOURCE only (#149)".

The fifth assertion. Migrated here as SubgraphManifest.t.sol — testManifestAbiIsAnArtifactThisRepoPublishes holds the manifest's ABI path against LibCopyArtifacts.contracts(), testManifestIndexesTheInterfaceEvent and testIndexedArtifactDeclaresTheIndexedEvent hold the event signature against IMetaV1_2. In the rainix-sol lane, no docker.

Both required verifications are recorded — matchstick green on the stubbed manifest (10/10, run 32520179023) and network: template accepted by codegen and by build --network for all five networks, with build --network failing loudly when networks.json is absent.

---

One item from this issue is deliberately not on main, and it is not a regression: the regenerate-and-diff snapshot guard in "What this recovers". The comment above already corrected that section — crates/metaboard/src/schema/metaboard.graphql is the full graph-node API schema, not an entity projection, so a faithful generator means reimplementing graph-node's API-schema derivation, and it was split out as a follow-up rather than folded into the split PRs. crates/cli/src/cli/schema_check.rs is still in place, unchanged.

That follow-up does not appear to have an issue filed for it yet. Not filing one from here — flagging it so the decision stays with a human.