ci(netlify): build @coasys/ad4m from source (dev branch)

[HexaField]

ci(netlify): build @coasys/ad4m from source on deploy previews

What

Netlify deploy previews can clone an ad4m branch, build the SDK from source, and link it into
the WE workspace before the normal build. The preview site picks up SDK work — batch RPC endpoints,
performance fixes, new handlers — without waiting for a new pre-release tag. Which ad4m branch is
decided per pull request; left alone it tracks dev.

The published site is unaffected and keeps installing the version pnpm.overrides pins.

Why

WE's pnpm override pins a published pre-release tag (0.13.0-test-model-layer). New SDK features
land on ad4m's dev branch well before a tag gets cut, and the tag only moves when somebody
hand-publishes one from an ad4m commit. The gap means the preview site runs stale SDK code even
when the executor already supports the new endpoints.

At time of writing ad4m dev is 19 commits ahead of 54a3fd956, the commit the current pin was
published from, with nothing behind — so this is the ordinary state of things rather than a moment
that happened to be bad.

Concrete example: PerspectiveProxy.subjectClassTargetClasses() (ad4m#979, merged 8 Sept) is a
single-call presence check for a set of models, replacing one queryLinks per model — ~4.5s on a
16-model space switch against a 300ms-RTT executor. It is in those 19 commits and not in the pin.
That is the same ground #190 covered from this side.

Correction to the original description: getAllShacl() was the example given, and it is
already in the pinned tag as a single perspective.getAllShacl RPC — which is why
getForeignShacl typechecks on dev. The argument holds; the method named was the wrong one.

How

• scripts/netlify-build.sh — shallow-clones ad4m, builds @coasys/ad4m from source (3 deps,
  fast), rewrites the pnpm override to link: the local build, then runs pnpm build.
• netlify.toml — points [context.deploy-preview] at the script. [build] keeps
  pnpm build, so production, branch deploys and every other context stay on the pin.
• Which ad4m, in the order the answers are consulted:
  1. AD4M_BRANCH in the Netlify UI — site-wide, overrides everything below.
  2. A preview:ad4m@<ref> label on the pull request. preview:ad4m@pin means "use the pinned
     version", for a branch whose whole point is that pin.
  3. An ad4m branch of the same name as the WE branch — the cross-repo case.
  4. dev.
• The build says what it built: the resolved ref and SHA are written to /build-info.json and
  announced in the console, plus a we:ad4m-build meta tag.
• GitHub Actions CI stays untouched — it keeps building against the published SDK version.

Why the context scoping

[build] covers every deploy context, so as originally written the change governed the published
site too. The pin is a claim about which executor a build requires — VERIFIED_AGAINST_AD4M in
@we/backend-ad4m names both a version and an ad4m commit, and the Rust half is published nowhere
at all — and the published site has to keep making that claim, because the people opening it are
running whatever executor they installed. A preview is the opposite case: it is tried against an
executor somebody has in front of them, which during cross-repo work is a build rather than a
release.

Why per-PR rather than hardcoded dev

Hardcoding the branch reproduces, on the preview surface, what 23927712 took out of CI in August:
an artefact defined by whatever another repository held at the moment the job ran. Same-name branch
matching is revived from the old build-with-ad4m-link.sh, and is what ad4m-compat.yaml still
does.

A label rather than a committed marker file because a label cannot merge. A file saying "build
from dev" would land on dev and go on governing every later preview until somebody noticed.

The branch name is read from the pull request rather than from BRANCH, which Netlify sets to
pull/N/head on a preview — one request, and the labels come back with it.

Test plan

• Deploy preview builds green with the script running the source path end to end.
• /build-info.json on the preview reports "ad4mSource": "source", "ad4mRef": "dev",
  "ad4mSha": "cf1f69597…" — the #979 merge commit.
• The we:ad4m-build meta tag and console line are present in the served page.
• Ref resolution exercised for all four answers, including REVIEW_ID=194 against the live
  GitHub API (resolves ci/netlify-ad4m-dev, no label, no matching ad4m branch → dev).
• Build-info injection tested for the source path, the pin path, and a missing dist.
• bash -n clean. Prettier does not parse .toml or .sh, so format:check skips both.
• preview:ad4m@pin — the path a deploy preview cannot exercise on its own. Tested by labelling
  the PR and running the script locally with REVIEW_ID=194, so the label was read off the live
  API: resolves to pin, skips the clone (/tmp/ad4m-sdk never created), builds against
  @coasys+ad4m@0.13.0-test-model-layer (named in the bundler's own module resolution), reports
  "ad4mSource": "pin" with a null SHA, and leaves the working tree clean — the pin path does
  not rewrite package.json, so it cannot trip the build-drift gate. Label since removed.

Known follow-ups

• link: is kept rather than file:. The linked package's deps were installed in place by npm;
  file: would have pnpm re-resolve them against WE's lockfile.
• No caching. Every preview build re-clones and re-compiles ad4m core; ad4m-compat.yaml caches on
  the ad4m SHA and this could too.
• The executor half is still unaddressed. This picks an SDK; the pin also names an ad4m commit for
  the Rust side, and nothing here builds or checks one.

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for coasys-we ready!

Name	Link
🔨 Latest commit	c0fce79
🔍 Latest deploy log	https://app.netlify.com/projects/coasys-we/deploys/6aa1bf254bb23c000893a4fb
😎 Deploy Preview	https://deploy-preview-194--coasys-we.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.