agentsclimarketplace

Engine release

Skill Hellblazer/nexus/.claude/skills/engine-release

Use when cutting or deploying the Java engine-service binary (engine-service-vX.Y.Z), refreshing the cloud engine, or validating develop's engine tip in the cloud. This is the SECOND release lifecycle — separate from, and not gated by, the conexus PyPI release (use the `release` skill for that). Authority: AGENTS.md § Engine-service release.From its SKILL.md

Install
npx -y skills add Hellblazer/nexus --skill engine-release

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 6 stars6 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

34.0 KB, as published. Nobody here has run it

Engine-service Release Checklist

The Java engine-service is a separate release artifact from the conexus PyPI package. Cutting it is lightweight, frequent, and NOT gated by the luxe6 / RDR-155-P4a develop release boundary — so the cloud engine can (and must) be kept current with develop's engine tip independently of develop being unreleasable. Conflating the two lifecycles is how the cloud engine silently drifts (2026-06-26: 22 service/ commits / 4 days un-deployed, un-cloud-tested).

Follow in order. Releaser is human: AI preps + validates; the human pushes the tag.

Steps

1. Decide whether a cut is needed (drift check)

git tag -l "engine-service-v*" | sort -V | tail -1     # last engine tag
git log --oneline <last-engine-tag>..HEAD -- service/   # what engine changed since

Cut a fresh engine when service/ has accumulated cloud-relevant work: pooler/RLS, pgvector, catalog conformance (RDR-168), aspect queue (RDR-163), batch endpoints, embedder. Don't let it pile up — a large unvalidated engine delta means any "cloud test" result is testing a stale binary, and any PyPI release pinning that tag ships behind.

2. Verify the engine is green on the exact commit you'll tag

The version is tag-stamped — there is NO manifest to bump (release.properties release_version is blank in source, stamped at native-build time from the tag; the Maven pom stays 1.0-SNAPSHOT).

Confirm the full Java suite + native build passed on the exact service/ tree:

# fast path: if service/ at HEAD is byte-identical to a green service-ci commit, that CI covers it
git diff --stat <green-service-ci-sha> HEAD -- service/    # empty = covered
# else run locally (needs Docker for Testcontainers pgvector + the bge ONNX model):
scripts/mvnw-leased.sh -q test

The Java CI (service-ci.yml) is advisory — it does not block auto-merge — so verify it actually passed on this tree rather than assuming.

3. PRE-TAG gate: --shakeout (the leg that builds the candidate)

--guided IS RETIRED — do not use it. RDR-155 P4b (commit 7e47c285, 2026-07-24) deleted nx guided-upgrade / migrate-to-service / storage migrate all, so --guided, --cold and --hole-punch now refuse at the arg loop with a RETIRED message and exit 2. This step named --guided for one cut after the retirement and would have failed the next engine cut at the gate. --chash-window is ALSO RETIRED (nexus-lgdel.l2, 2026-08-16): its entire subject was the pre-cutover legacy 32-hex chash window (RDR-180), a capability deleted along with nexus.chash_alias; the leg, its Dockerfile, and its rehearsal script are gone. Surviving journeys: --era-hop, --package-upgrade, --shakeout, --fullstack, --stranded (nexus-8nlj4: two-hop stranded-redirect — armed-detector refusal + pin-side migration; weekly heartbeat via stranded-redirect-rehearsal.yml, dispatch it on demand when a cut touches stranded_install.py or the migration-rehearsal harness), --candidate-migration (nexus-z0ylb: the locally-built CANDIDATE engine's full Liquibase walk over a POPULATED store — provisions the PUBLISHED FLOOR engine for real, populates through it (content + catalog manifests + a real taxonomy-discovery pass), hand-swaps the candidate binary in with the provenance sidecar's tag/version kept pinned at the floor (HARNESS bookkeeping, not a production technique — a real release install-binary's an honest sidecar at download time; this rewrite only keeps a LATER assert in the SAME test run from silently re-acquiring the floor over the candidate mid-rehearsal, and a nx daemon restart-stale --dry-run no-op check inside the leg proves exactly that, nothing broader), then boots and asserts the changeset delta plus EXACT row invariants — see the leg's own coverage statement below for what it does and does NOT prove), and the default rehearse.sh (Phases A/D/E).

Ordering, still load-bearing. --shakeout BUILDS the candidate locally (run.sh does the GraalVM -Ob native build; only the retired --cold path skipped it and acquired a PUBLISHED binary instead). --candidate-migration ALSO builds the candidate locally (same -Ob build, stamped with the floor version) — the two legs are complementary, not redundant: --shakeout proves the candidate's CLI-verb/concurrency surface on a fresh install; --candidate- migration proves its Liquibase walk over populated data. --with-cloud exercises the conexus-DEPLOYED service, so it cannot run pre-tag either — it is part of the post-deploy cloud gate (Step 6).

tests/e2e/migration-rehearsal/run.sh --shakeout

Must end CANDIDATE SHAKEOUT PASSED.

Phase F now runs service/native-smoke.sh's own probe set too (nexus-l8xnz, 2026-08-17). The raw-curl probe set (taxonomy/assignments/details' 64-hex doc_id width validation, T1's separate-jOOQ-schema reflection check, the memory/plans/taxonomy/chash routes, the bge-768 embed path, the fused-rerank stage) used to run ONLY inside engine-service-release.yml — a stale probe fixture (the pre-fix 16-char doc_id literal) burned the v0.1.77 tag on both linux release legs while the binary itself was fine, and --shakeout stayed green because nothing local ever exercised the script. --shakeout now drives the IDENTICAL script (byte-for-byte; only the caller is adapted) against the candidate over the already-provisioned Postgres — a stale probe now fails --shakeout locally, before a tag is ever cut. This does not replace --acquire below (which drives the SIGNED, PUBLISHED bytes) — it closes the "release-workflow-only procedures rot silently" gap for the script's own assertions, not for signing/codesign/cosign/PG-bundle packaging defects, which remain --acquire-only by construction (see below).

--candidate-migration — MANDATORY whenever this cut's service/ delta touches db/changelog/** (a new or modified Liquibase changeset); optional otherwise (a cut that only touches Java handler/repository code with no schema change has nothing new for this leg to prove beyond what --candidate-migration already proved on a prior cut of the same schema generation — run it anyway when in doubt, it is not expensive relative to --shakeout). MANDATORY here means "this class of change gets no other pre-tag rehearsal against populated data," not "this leg proves the changeset is safe in every dimension" — read the coverage statement below before treating a green run as exhaustive:

tests/e2e/migration-rehearsal/run.sh --candidate-migration
# a cut whose changeset count is known ahead of time pins it instead of
# merely reporting it, e.g. a cut adding exactly 3 new changesets:
EXPECT_NEW_CHANGESETS=3 tests/e2e/migration-rehearsal/run.sh --candidate-migration

Must end CANDIDATE-MIGRATION REHEARSAL PASSED. Reports (never asserts to an exact value unless EXPECT_NEW_CHANGESETS is set) the changeset delta between the floor's post-init DATABASECHANGELOG count and the candidate's post-boot count — delta=0 is a legitimate, explicitly-stated outcome (it still proves boot-over-populated-store + checksum stability + grants idempotence), not a silent skip.

Coverage — what this leg DOES and does NOT prove (substantive-critic finding, 2026-08-14, T2 nexus/critique-nexus-z0ylb-candidate-migration-rehearsal-2026-08-14 [22547] — the leg's own script header carries the identical statement, kept in lockstep). It exercises: boot succeeding over populated data (a changeset that silently assumes an empty table fails here, not at a customer's box); RLS not going DML-blind mid-migration; a changeset's own GRANT/ownership statements not bricking boot; CASCADE fallout on a DROP TABLE; and checksum/row-count integrity (Liquibase's own checksum re-validation plus this leg's EXACT row-invariant asserts, now spanning chunks, catalog manifest/documents, taxonomy centroids AND topic_assignments).

It structurally CANNOT catch two classes, by construction of what this leg seeds:

  • Cross-shard PK collision (the "cross-shard collision" DO $$ guards that vectors-004/taxonomy-007-style changesets carry) — this leg seeds ONE embedding dimension (bge-768) only; reproducing a genuine collision needs a second populated dimension sharing a colliding key.
  • Planner-statistics flips from a stats-absent post-migration table picking a different query plan under real data volume — this leg's corpus tops out around ~190 rows, far too small to exhibit one. That class is pinned at the JAVA layer instead: SchemaMigratorIntegrationTest::rdr180Rewrite_leavesPlannerStatsFresh (service/src/test/java/dev/nexus/service/SchemaMigratorIntegrationTest.java).

This is strictly stronger than the --guided gate it replaces. It performs the same native-image build — the -Ob quick build has the SAME reachability requirements as the full release build, so it catches a broken native build before the tag burns a release-workflow run — and then adds the full CLI-verb matrix, incremental index, and (nexus-xm0cp) a CLIENT-SIDE census over the concurrent load phase against that binary — the candidate has no request logger (com.sun.net.httpserver, no access-log appender), so there is no service-side 5xx signal to scan. The census has TWO parts, not one: (1) none of the concurrent nx store put / nx index repo calls exit non-zero, and (2) none of them logs an absorbed vector_gateway_retry either — coverage gap (1) alone would miss it: HttpVectorClient retries a 502/503/504 within a bounded budget BEFORE ever raising (_GATEWAY_RETRY_CODES, src/nexus/db/http_vector_client.py), so a gateway blip that resolves in time never reaches a client exit code at all, exactly the shape a lock convoy is most likely to take. Part (2) closes that gap by scanning each call's log for the retry's own structlog line. A FAIL here is a product finding, not a harness formality: its maiden runs caught two production bugs the unit suites missed (nexus-h8rf6).

Notes:

  • The host JVM suite (scripts/mvnw-leased.sh -q test, Step 2) validates the Java on the JVM; --shakeout adds the native-image build + serve + drive.
  • Do NOT use release-sandbox.sh — it swaps the uv tool venv and can break the live install. The container rehearsal is the safe, isolated one.
  • When the two-hop stranded-redirect rehearsal lands (nexus-8nlj4) it becomes the acceptance journey that replaced the retired guided legs; add it here then, alongside --shakeout rather than instead of it.
  • --candidate-migration requires a native build the same way --shakeout does and refuses --no-build; it does NOT combine with any other leg (standalone entrypoint, same discipline as every other journey in this harness).

3b. Client-release preconditions — a DEPLOY gate, NOT a tag gate

uv run python scripts/check_client_release_precondition.py --engine-tag engine-service-vX.Y.Z

Some engine changes BREAK clients that predate a specific client commit (the nexus-9ssih dangling-endpoint 400 is the canonical case — its first landing was REMOVED by 6714e70e to wait for the client half). This script refuses (exit 1) until every client commit the tag requires is an ancestor of the latest RELEASED v* tag. Register new preconditions in the script's ENGINE_CLIENT_PRECONDITIONS whenever an engine change ships a wire behavior old clients mishandle. Prose deploy-gates get skipped; this one does not.

This is also where the mechanized both-halves wire-contract ledger (docs/wire-contract-pending.md, scripts/check_wire_contract_pairing.py) gets consulted on the unpaired deploy path (protocol-audit [22511] Gap 1, 2026-08-14) — an ordinary "refresh the cloud engine" run with no paired client release in flight. A non-empty ## Unshipped section blocks (exit 1) regardless of --engine-tag unless every entry's bead is acknowledged:

uv run python scripts/check_client_release_precondition.py --ack-client-lag nexus-1234

A red exit blocks the DEPLOY, never the tag cut (Hal directive 2026-08-02; the pre-tag wiring of this check is what forced conexus 7.1.0 to ship pinned to a pre-fence engine — its own flagship feature inert on fresh local installs). A tag gates DELIVERY, not work, and not even publication: cut the engine tag whenever the tree is green. On a red exit here, the tag still cuts; the DEPLOY waits for the client tag that carries the listed commits. The paired-release choreography (AGENTS.md § Engine-service release) closes the gap: the client release bumps the floor to this tag IN the same release, and the deploy fires at client-tag push, in parallel with the PyPI publish — satisfied the instant the client tag exists, live before any user can install the client that requires it.

3c. PRE-TAG gate: published-client write leg (published-client-write-gate.sh, nexus-86mx2)

tests/e2e/published-client-write-gate.sh

Must end PUBLISHED-CLIENT WRITE GATE PASSED. Runs the CURRENTLY-PUBLISHED conexus client (real PyPI, scrubbed-HOME sandbox — same isolation idiom as fresh-install-mvv.sh --published) against THIS candidate engine (working- tree dev jar by default via scripts/build-gate-jar.sh; NEXUS_SERVICE_TAG=engine-service-vX.Y.Z points it at a specific published tag instead) and asserts REAL catalog registration — manifest ROW COUNT via GET /v1/catalog/manifest/verify, exact expected count, never a 200 alone — for a store put and an index md write.

Why the other legs do not cover this. Every other gate in this checklist tests a CONSISTENT client/engine pair: the host JVM suite and --shakeout are develop×develop; --acquire is the WORKING-TREE client against a published engine; --package-upgrade proves an EXISTING install's engine converges, never a fresh client's WRITE path against a stricter successor. None of them is "the client every user currently has, writing against the engine about to ship." That gap is exactly how engine-service-v0.1.73's RDR-191 GATE-2 constraint (manifest writes must name their collection) 400'd every released-7.6.1 manifest write in PRODUCTION while every gate above stayed green (T2 22488/22489, nexus-sh9v2 — 910 live documents accumulated invisible to catalog-aware retrieval before anyone noticed). This leg would have caught it here, before deploy, instead of in production.

A published client KNOWN to be incompatible with the current engine (the exact window before a client release ships the fix) is not a tag-cut blocker — acknowledge it explicitly and by name:

NX_EXPECTED_CLIENT_LAG=nexus-sh9v2 tests/e2e/published-client-write-gate.sh

Exits 2 (PUBLISHED-CLIENT WRITE GATE EXPECTED-INCOMPATIBLE) — a named, counted state, never a silent pass. The script refuses the acknowledgment (hard-fails instead, exit 1) once the published client it actually resolves is >= the version its own header names as the fix — an ack held past its expiry is exactly the drift this gate exists to catch. See the script's own header for the full contract; do not re-derive it here.

3d. PRE-TAG gate: RDR-194 D4 cloud-count-5 delivery precondition (nexus-tk070.p5a)

uv run python scripts/check_rdr194_cc5_delivery_gate.py --ref HEAD

Only relevant when this cut's service/ delta carries taxonomy-014-topics-tenant-unique.xml (RDR-194 P5a) — the gate exits 0 immediately, without ever consulting T2, when that file is absent from --ref. When it IS present, the gate blocks (exit 1) unless a T2 record at (nexus, cloud-count-5-measured) carries an explicit MEASURED-zero reading for all three cross-tenant sub-populations (topic_assignments, topic_links, topics.parent_id — see the script's own header for the exact record contract). nx unreachable is exit 2, UNVERIFIABLE — never a silent pass, same fail-closed doctrine as check_engine_release_floor.py (mold this gate copies). Mirrors that gate's shape: a mechanical pre-tag check replaces what would otherwise be a P7 human-checklist item alone — see nexus-i5c2u for why an eyeball-only version of this class of check has already burned this project once (9+ days of cloud engine drift that nothing caught).

3e. PRE-TAG check: new /version fields need a PAIRED conexus edge-allowlist change (nexus-04sff)

The public edge (api.conexus-nexus.com) does NOT pass the engine's /version body through verbatim — it trims it to a deliberate, reviewed ALLOWLIST (conexus-24c4: schema_* fields fingerprint the DB journal and schema_error can carry raw exception text, so verbatim pass-through was rejected by design and stays rejected). Any NEW field the engine adds to /version is therefore dead at the edge until conexus adds it to that allowlist — exactly how nx_answer_steps_supported (engine-service-v0.1.85) shipped engine-green through every gate above and then read as absent to every cloud client (cloud-client-path-gate leg A FAILED 2026-08-21, nexus-04sff / conexus-f6w7; same class as nexus-bwulw).

Before pushing the tag: git diff <last-engine-tag>..HEAD -- service/src/main/java/dev/nexus/service/http/VersionHandler.java. For every field ADDED, surface a REQUEST relay to conexus naming the field and the engine tag ("add <field> to the edge /version allowlist, mirror-don't-invent: absent on older engines stays absent") and record the conexus bead id on the nexus bead before the tag — the edge half must be live before Step 6.1 can pass, and Step 6.1 is what gates the paired client release.

4. Push the tag (human, or AI when explicitly authorized)

Releaser is human by default (AI preps + validates); the human pushes the tag, OR the AI pushes it when the human explicitly authorizes that cut.

git tag -a engine-service-vX.Y.Z -m "engine-service X.Y.Z" <commit>   # <commit> must be on origin
git push origin engine-service-vX.Y.Z

Tag-push fires engine-service-release.yml → builds + cosign-signs the 3 native binaries for the supported targets (linux-amd64, linux-arm64, mac-arm64) plus their PG bundles, and publishes the GitHub release. (Intel macOS / mac-amd64 is NOT a supported target — not built.) Publishes nothing to PyPI. Wait for the workflow to finish publishing before Step 5 (prior runs ~30 min).

5. POST-PUBLISH gate: --acquire (the leg that drives the PUBLISHED bytes)

Wait for engine-service-release.yml to finish publishing, then:

NEXUS_SERVICE_TAG=engine-service-vX.Y.Z tests/e2e/migration-rehearsal/run.sh --acquire

Must end ACQUIRE GATE PASSED. Standalone — do not combine with other legs. The tag is REQUIRED and never defaulted (the point is a specific published artifact); run.sh exits 2 without it.

What it does on a bare box: quarantine asserts (no nx binary pre-staged, no system PostgreSQL) -> nx daemon service install-binary <tag> cold-acquires the native binary + PG bundle, cosign-verified -> init --service -> /version asserts release_version equals the acquired tag -> store / index / search drive it -> doctor with no ✗.

Why --shakeout does not cover this. Step 3 drives the LOCALLY BUILT -Ob candidate. The published artifact is different bytes from a different builder: full native build (not quick-build), codesign, cosign, PG-bundle packaging. A defect introduced by the release workflow is invisible to the local shakeout BY CONSTRUCTION — nexus-2oh5q is exactly that hazard (signing breaking JNI dlopen of the bundled onnxruntime/DJL), dormant only while the Apple secrets are unprovisioned. Historically this gate caught nexus-pi3s3 + nexus-qeoxf (2026-06-26), defects every local suite missed.

Scope limit, carried from nexus-1ddsy's close: the container is Linux, so this exercises the linux artifact. The mac-arm64 post-signing path is NOT covered here — tracked on nexus-2oh5q.

The mac-arm64 gap has a gate — it is just MANUAL and not yet armed. The provisioning half (six Apple credentials, both portals, the pre-flight and the renewal failure modes) is docs/operations/apple-code-signing.md. Once those are provisioned and the first Developer-ID-signed tag publishes, run on an arm64 Mac, BEFORE setting APPLE_SIGNING_REQUIRED=true:

NEXUS_SERVICE_TAG=engine-service-vX.Y.Z tests/e2e/mac-signed-binary-gate.sh

Must end MAC SIGNED-BINARY GATE PASSED. It downloads the published mac-arm64 artifact, applies the quarantine xattr a browser download would set (the API path install-binary uses sets none, which is why this hazard has never bitten anyone), asserts Developer-ID signature + Hardened Runtime + the disable-library-validation entitlement + spctl acceptance, then boots the SIGNED binary through native-smoke.sh and asserts the bge-768 embed actually executed — the DJL tokenizer JNI + onnxruntime System.load()s are precisely what Library Validation refuses. A skipped embed is a FAILURE there, not a pass.

Why it cannot be a CI job: mac-arm64 is smoke: false (macos-14 runners have no Docker) and codesign runs AFTER the linux-only smoke, so CI never boots the signed mac bytes at all. codesign --verify cannot see a runtime dlopen refusal.

--package-upgrade is NOT a substitute (checked; do not re-derive): it converges to NEW_ENGINE_TAG, which run.sh derives from REQUIRED_ENGINE_VERSION — the release's engine identity, not an arbitrary tag — so it can only validate a tag a PyPI release has already pinned, strictly after the moment this gate protects.

History: this step said "CURRENTLY NO LEG / escalate to Hal" for one cut after RDR-155 P4b retired run.sh --cold (whose TAIL drove the deleted nx guided-upgrade; its acquire half never did). nexus-1ddsy rebuilt the acquire half as --acquire and it gated engine-service-v0.1.55 in production (11 PASS / 0 FAIL). Hal REFUSED "accept the gap" on 2026-07-24 — do not re-propose it. Instance of nexus-1e2eh (release-only procedures rot silently).

--with-cloud does NOT belong here. It is NOT a local/acquire leg — it exercises the conexus-DEPLOYED cloud service, so it can only run AFTER the engine is deployed to api.conexus-nexus.com (Step 6). Running it pre-deploy tests the previously-deployed cloud engine, not the candidate. It is part of the post-deploy cloud-gate, below.

5b. Migration-release branch (CONDITIONAL — this tag carries schema or data DDL)

Trigger: service/ since the last engine tag includes a new Liquibase changeset, or any change to a data shape existing rows already have to conform to (T2 [22511] gap 9). Skip this step entirely when the cut carries no such change.

  1. Representative-scale rehearsal. Run the populated-store rehearsal in PUBLISHED-bytes mode against a corpus seeded ABOVE a stated floor, not the harness's default toy seed (10-30 docs across rehearse_cold.sh / rehearse_acquire.sh / rehearse_shakeout.sh / rehearse_hole_punch.sh):

    NEXUS_TARGET_RELEASE=<published-conexus-version> tests/e2e/migration-rehearsal/run.sh --package-upgrade
    

    Name the floor and the actual seed count used in the deploy relay. RDR-191's cloud 385,484-row unify-chunks migration (T2 [22485]) remains the only at-scale proof this project has produced for a chunk-table DDL change — and it ran in PRODUCTION. If the rehearsal cannot be brought to a genuinely representative scale before the deploy relay fires, say so explicitly rather than letting a toy-scale pass stand in for one.

  2. Rollback decision point, settled before the relay fires. Determine whether this migration can be rolled back after it commits on the managed deployment. Non-transactional DDL (CREATE INDEX CONCURRENTLY, any Liquibase changeset that cannot run inside a transaction) forfeits the free atomic rollback a transactional migration gets — nexus-o8dil.22's own wording: "CIC, non-blocking, +11%, cannot run in a transaction, and therefore forfeits the free atomic rollback that the local path gets." When the answer is no, write IRREVERSIBLE in the deploy relay verbatim, and have the substitute in hand before the operator opens the window: a written rollback/abort runbook with exact statements and named abort criteria.

  3. Freeze-window derivation from measurement, not a guess. Generalizing nexus-o8dil.22's pre-flight (T2 [22420] / [22427] / [22485]): derive and state (a) copy-peak — the largest transient storage footprint the migration needs mid-flight; (b) WAL budget — retained WAL under the deployment's replication settings during the window, checked against max_wal_size; (c) disk floor — abort unless available disk clears (steady-state floor + copy-peak) with a stated margin, re-measured immediately before executing (corpus growth between planning and execution shrinks the margin). Name the resulting threshold and the abort condition in the operator runbook.

  4. Post-deploy data-integrity verification, beyond /version. A version match proves the binary shipped, not that the data survived. Verify, per T2 [22485]'s pattern: exact row-count reconciliation pre vs. post (per dimension/table, not an aggregate), that ANALYZE actually fired, and that Step 6.1's client-visibility gate plus the deploy gate's parity/recall legs are green post-migration. [22485]'s own verdict is the bar to match: "ROW INVARIANT EXACT: 385,484 pre == post ... ANALYZE fired ... STEP-6 green (112/113 parity, recall 12/12 pools identical), cloud client-path gate PASSED all four legs."

Full rationale and evidence citations: docs/contributing.md § Schema/data-migration releases.

6. Relay deploy + post-deploy cloud validation to conexus (passive bus)

Deploy and cloud-validation are conexus-side operations — the bus is passive, so surface an explicit relay to Hal; never frame the cross-instance deploy as autonomous:

relay: deploy engine-service-vX.Y.Z to api.conexus-nexus.com + re-run the cloud gate (recall + hybrid parity, xr7.8.9-style).

THIS is where 3b's precondition check blocks. Re-run check_client_release_precondition.py --engine-tag <tag> before surfacing the relay: a red exit means the deploy waits for the client tag carrying the listed commits. In the paired-release choreography that is not a long wait — the deploy relay fires at client-tag push, in parallel with the client's PyPI publish, so the precondition is satisfied the instant the client tag exists and the engine is live before any user can install the client that requires it.

The post-deploy --with-cloud rehearsal (run.sh --with-cloud, the cloud → cloud Voyage journey) requires the candidate to be deployed on conexus first — it runs as part of this cloud-gate, once the deploy lands, not in Step 5. For cross-repo gate / deploy status, read the authoritative bead + the conexus bus, not memory — cross-repo state goes stale fast (2026-06-26: a luxe6 condition had been cleared a week earlier than memory implied).

6.1. Post-deploy client-visibility gate (MANDATORY, run from a cloud-mode box)

tests/e2e/cloud-client-path-gate.sh

Run this AFTER Step 6's deploy relay confirms the tag is live, and BEFORE Step 7's downstream-ref bump or signing off any release shakeout that depends on this engine (T2 [22511] gap 7 — this gate existed only as one prose line in AGENTS.md, in no numbered step of this checklist, since it was born from the nexus-bwulw incident). The gates above prove the ENGINE works, direct; they do not prove the PUBLIC edge (api.conexus-nexus.com) exposes the same contracts — 2026-07-23 (nexus-bwulw): the edge stubbed /version and auth-gated /health, silently disabling voyage threshold gating and dimension-orphan tooling and blocking guided migrations to cloud, while three client features shipped green through every engine-direct gate above. This asserts the engine's pinned contracts (/version fields, the ez5.1 /health contract, the client embedding_mode probe, the /v1 read path) survive the public edge.

Client version to run it from: the working tree (HEAD), the same dev-client × new-engine pairing every other gate in this checklist uses — this script has no separate published-client mode. It is NOT a substitute for Step 3c's published-client-write-gate.sh, which is the leg that pairs the CURRENTLY-PUBLISHED client against the candidate; this step's job is edge-contract visibility, not client-write compatibility.

7. After conexus confirms deployed + cloud-gated green, bump downstream refs

  • tests/e2e/migration-rehearsal/run.sh COLD_TAG default → the new published tag (or override via NEXUS_SERVICE_TAG).
  • When the NEXT PyPI release bumps REQUIRED_ENGINE_VERSION to this tag, also rotate run.sh's NEXUS_PREV_RELEASE/NEXUS_PREV_ENGINE_TAG defaults (the --package-upgrade convergence leg's starting point — must stay one release BEHIND the new dependency or its staleness guard fails loud; nexus-cfgo9). The --package-upgrade leg itself runs in the PyPI release skill's Step 1, not here — this skill only keeps its inputs fresh. The unit is RELEASES, not engine tags — a SKIPPED engine tag does NOT rotate them (2026-08-11). PREV_ENGINE_TAG is the engine the PREVIOUS RELEASE PINNED. An engine tag that is cut, published, and gated but never pinned by any release (v0.1.70: a defect was found after the cut, so 7.6.0 shipped v0.1.71) is a skipped version — rotating PREV_ENGINE_TAG onto it would point the rehearsal's "previous install" at a hop no user ever made. At the 7.6.0 bump the correct values stayed 7.5.0 / engine-service-v0.1.69 while COLD_TAG moved to v0.1.71. The staleness guard only fires when PREV collapses to EQUAL the floor; it does NOT catch "rotated onto a tag no release shipped", so check this by hand at every bump.
  • COLD_TAG moves at EVERY floor bump, unconditionally — TestDownstreamConsumersTrackTheFloor::test_cold_rehearsal_tag_is_at_least_the_floor requires COLD_TAG >= REQUIRED_ENGINE_VERSION. A comment in run.sh once said not to bump it (true about runtime effect, since --cold is retired; false as an instruction) and following it blocked the 7.6.0 battery. A prose comment that contradicts a mechanical test loses to the test.
  • SchemaUpgradeRehearsalIntegrationTest.OLD_TAG (service/src/test/java/dev/nexus/service/) → the PREVIOUSLY-deployed tag (nexus-7z6s7 rotation policy: the old→HEAD rehearsal's "real aged box" realism rots as the fleet moves on; re-verify the two structural preconditions documented on the constant when bumping) OLD_TAG rotation is a THREE-part edit (nexus-gm38i): regenerate the changeset snapshot (uv run python scripts/gen_rehearsal_hop_manifest.py), re-derive the new hop's row-DML seed coverage, and re-point the data leg's seeding + its SEED-COVERAGE block + the lint's DECLARED_SEED_COVERAGE together — tests/test_rehearsal_seed_coverage_lint.py fails loudly until all three agree.
  • REQUIRED_ENGINE_VERSION (src/nexus/engine_version.py) MUST move to this tag — unconditionally, not "only if the release needs the features". There is ONE engine identity per release: the engine it was built and gated with, on EVERY install path (Hal directive 2026-07-15, after the 14h GH #1402 incident). It is NOT a compatibility minimum. For local-mode installs this constant is the ONLY delivery vehicle — an engine tag that is cut, gated, and never pinned reaches nobody. PINNED_SERVICE_TAG is DERIVED from it, so the one edit moves both. Sequencing — PAIRED release (Hal directive 2026-08-02, supersedes "bump lands with the NEXT release AFTER deploy"): the bump rides the client release PAIRED with this engine's deploy — same release, not the next one (floor-lag ships a client whose pinned engine lacks the engine halves of its own features: the 7.1.0/v0.1.62 inversion). The deploy relay fires at client-tag push, parallel with the PyPI publish (Step 6), so the engine is live before any user can install the floor-bumped client. GH #1402's lesson stands as: never publish a floor-bumped client with NO deploy armed — the deploy fires at tag push, not "eventually". scripts/check_engine_release_floor.py fails the release if a gated tag was never pinned. The client-side release skill's Step 0 runs this gate with --paired-deploy engine-service-vX.Y.Z (nexus-k1c08) to distinguish the expected pre-deploy cloud-behind state from real drift — this skill only needs to ensure the tag it just cut is what that flag names.

8. Record state (T2) — guarded by a live /version read (DO NOT SKIP)

nx service record-deploy engine-service-vX.Y.Z --commit <sha> --gate PASSED

This GETs the deployed service's /version, ASSERTS release_version == X.Y.Z, and only then writes the deployed-engine-version tracker. The recorded version is machine-sourced from the live read — never hand-typed — so it cannot disagree with what the cloud is actually running, and running it before the deploy lands fails loud instead of recording a wrong fact (nexus-dz6b1 / RDR-179).

Scope honesty: this guards the value (no wrong version can be recorded); it does NOT force the step to run. The original v0.1.17-stale-across-three-deploys incident was an OMISSION, not a fat-finger — so this step is still skippable and you must not skip it. Closing the omission vector for good (cloud-gate writes the tracker on pass) is a tracked follow-up. --commit/--gate are verbatim provenance, not verified against the deploy.

To read what the cloud is running WITHOUT trusting the tracker, use the live handshake directly: nx service probe (prints release_version). The tracker is a cache; /version is truth.

So the next session (and the engine-freshness gate in the release skill) can see what the cloud is actually running without re-deriving it.

Relationship to the PyPI release

The conexus PyPI release (the release skill) PINS one engine tag and gates on its cloud-validation (its Step 0 engine-freshness gate). This skill is what produces + validates the tag that gate pins. Run this whenever the engine drifts; run release only when shipping the Python package.

Keep looking

Skills are one crate of 610,220. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.