Add EveUnity release request contract

docs/eve-migration-roadmap.md

@@ -469,11 +469,14 @@ Recently cut:
 - EveUnity release lifecycle now carries a structured UPM release contract.
   `packages/org.gamecult.eve.unity-uitoolkit/eve-runtime-capability.json`
   names the package root, version source, tag pattern, artifact kind, and
-  owner-side publish proof for `org.gamecult.eve.unity-uitoolkit`. The
-  lifecycle smoke validates that contract against the package manifest, parity
-  compares it against the ledger, and the runtime-owner consumer smoke asserts
-  the exported release fields without pretending the tagged EveUnity release
-  already exists.
+  owner-side publish proof for `org.gamecult.eve.unity-uitoolkit`.
+  `tools/eveunity/eveunity-release-contract.mjs` now builds a
+  `gamecult.eve.runtime_release_request.v1` request from the runtime capability
+  manifest and UPM package manifest, deriving the `eveunity-uitoolkit-v{version}`
+  tag, package dependency set, and UPM artifact path. The lifecycle smoke
+  validates that contract against the package manifest, parity compares it
+  against the ledger, and the runtime-owner consumer smoke asserts the exported
+  release fields without pretending the tagged EveUnity release already exists.
 - EveUnity capture lifecycle now carries a structured pending capture contract.
   `captureContract` names the Unity UI Toolkit runtime, capture kind, PNG
   artifact pattern, conformance attachment point, required Aetheria provider

docs/parity-testing-harness.md

@@ -354,7 +354,10 @@ The parity harness validates those lifecycle claims against
 `tools/parity/parity-manifest.json` and checks that declared evidence paths
 exist. The current lifecycle proof is deliberately split:
 
-- release: incubating UPM package identity and import surface exist in Eve;
+- release: `tools/eveunity/eveunity-release-contract.mjs` builds a typed
+  `gamecult.eve.runtime_release_request.v1` request from the runtime capability
+  manifest and UPM package manifest; the tagged EveUnity release remains a
+  split blocker;
 - test: package-owned EditMode tests run through Aetheria in Unity batchmode,
   and Aetheria can build the package through Unity's generated project;
 - capture: `tools/eveunity/eveunity-capture-contract.mjs` builds a typed

packages/org.gamecult.eve.unity-uitoolkit/README.md

@@ -37,7 +37,7 @@ The runtime capability manifest is
 `eve-runtime-capability.json`. Its lifecycle section records the current split
 evidence:
 
-- release: incubating UPM package identity and import surface;
+- release: typed UPM release request contract and incubating package identity;
 - test: package-owned EditMode tests run through Aetheria in Unity batchmode,
   plus Aetheria consumer-build smoke through Unity's generated project;
 - capture: typed capture request contract and pending Unity editor or
@@ -47,6 +47,11 @@ The release stage also declares the UPM release contract:
 `org.gamecult.eve.unity-uitoolkit` is released from this package root, reads
 its version from `package.json`, and uses tag pattern
 `eveunity-uitoolkit-v{version}` once the tag is cut from EveUnity.
+`tools/eveunity/eveunity-release-contract.mjs` builds a
+`gamecult.eve.runtime_release_request.v1` request from the runtime capability
+manifest and UPM package manifest. The request names the package version, tag,
+artifact path, dependency set, and target `GameCult/EveUnity` repository without
+pretending Eve has published the tagged release.
 
 The test stage declares the Unity EditMode runner contract: the current runner
 is `scripts/run-aetheria-unity-editmode-tests.ps1`, runs
@@ -95,6 +100,12 @@ graduate to `EveUnity`. The capture contract smoke is:
 powershell -ExecutionPolicy Bypass -File .\scripts\run-eveunity-capture-contract-smoke.ps1
 ```
 
+The release contract smoke is:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\scripts\run-eveunity-release-contract-smoke.ps1
+```
+
 For Aetheria, the Unity evidence path is:
 
 - `powershell -ExecutionPolicy Bypass -File ..\..\scripts\run-aetheria-unity-package-smoke.ps1`

packages/org.gamecult.eve.unity-uitoolkit/eve-runtime-capability.json

@@ -73,11 +73,17 @@
         "versionSource": "packages/org.gamecult.eve.unity-uitoolkit/package.json",
         "tagPattern": "eveunity-uitoolkit-v{version}",
         "artifactKind": "upm-package",
+        "requestSchema": "gamecult.eve.runtime_release_request.v1",
+        "requestBuilder": "tools/eveunity/eveunity-release-contract.mjs",
+        "artifactPattern": "artifacts/eveunity-uitoolkit-release/{version}/org.gamecult.eve.unity-uitoolkit-{version}.tgz",
         "publishProof": "Tagged UPM release is created from the EveUnity repo and references this package root."
       },
       "evidencePaths": [
         "packages/org.gamecult.eve.unity-uitoolkit/package.json",
         "packages/org.gamecult.eve.unity-uitoolkit/README.md",
+        "tools/eveunity/eveunity-release-contract.mjs",
+        "tools/eveunity/eveunity-release-contract.test.mjs",
+        "scripts/run-eveunity-release-contract-smoke.ps1",
         "scripts/run-aetheria-unity-package-smoke.ps1"
       ],
       "pendingProofs": [

packages/org.gamecult.eve.unity-uitoolkit/eveunity-split-handoff.json

@@ -16,7 +16,10 @@
         "packages/org.gamecult.eve.unity-uitoolkit/package.json",
         "packages/org.gamecult.eve.unity-uitoolkit/README.md",
         "packages/org.gamecult.eve.unity-uitoolkit/Runtime",
-        "packages/org.gamecult.eve.unity-uitoolkit/Tests"
+        "packages/org.gamecult.eve.unity-uitoolkit/Tests",
+        "tools/eveunity/eveunity-release-contract.mjs",
+        "tools/eveunity/eveunity-release-contract.test.mjs",
+        "scripts/run-eveunity-release-contract-smoke.ps1"
       ],
       "destinationOwner": "EveUnity",
       "replacementProof": "Tagged UPM release cut from EveUnity rather than Eve incubation."

schemas/gamecult.eve.runtime_capability.v1.schema.json

@@ -236,6 +236,18 @@
                   "type": "string",
                   "minLength": 1
                 },
+                "requestSchema": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "requestBuilder": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "artifactPattern": {
+                  "type": "string",
+                  "minLength": 1
+                },
                 "publishProof": {
                   "type": "string",
                   "minLength": 1

scripts/run-eveunity-lifecycle-smoke.ps1

@@ -100,10 +100,16 @@ if ($releaseContract.packageName -ne "org.gamecult.eve.unity-uitoolkit") {
 if ($releaseContract.artifactKind -ne "upm-package") {
   throw "EveUnity release contract has unexpected artifact kind: $($releaseContract.artifactKind)"
 }
+if ($releaseContract.requestSchema -ne "gamecult.eve.runtime_release_request.v1") {
+  throw "EveUnity release contract has unexpected request schema: $($releaseContract.requestSchema)"
+}
 if (-not ($releaseContract.tagPattern -match "\{version\}")) {
   throw "EveUnity release contract tag pattern must include {version}: $($releaseContract.tagPattern)"
 }
-foreach ($pathProperty in @("packageRoot", "versionSource")) {
+if (-not ($releaseContract.artifactPattern -match "\{version\}")) {
+  throw "EveUnity release contract artifact pattern must include {version}: $($releaseContract.artifactPattern)"
+}
+foreach ($pathProperty in @("packageRoot", "versionSource", "requestBuilder")) {
   $relativePath = $releaseContract.$pathProperty
   if (-not $relativePath) {
     throw "EveUnity release contract missing $pathProperty"
@@ -117,6 +123,17 @@ $packageManifest = Get-Content -LiteralPath (Join-Path $projectRoot $releaseCont
 if ($packageManifest.name -ne $releaseContract.packageName) {
   throw "EveUnity release contract package name does not match package manifest: $($releaseContract.packageName) vs $($packageManifest.name)"
 }
+if (-not $packageManifest.version) {
+  throw "EveUnity release contract package manifest missing version"
+}
+if ($packageManifest.dependencies."org.gamecult.eve.surface" -ne "0.1.0") {
+  throw "EveUnity package manifest missing org.gamecult.eve.surface dependency"
+}
+
+& (Join-Path $projectRoot "scripts\run-eveunity-release-contract-smoke.ps1")
+if ($LASTEXITCODE -ne 0) {
+  throw "EveUnity release contract smoke failed with exit code $LASTEXITCODE"
+}
 
 $testContract = $manifest.lifecycle.test.testContract
 if ($null -eq $testContract) {

scripts/run-eveunity-release-contract-smoke.ps1

@@ -0,0 +1,95 @@
+param(
+  [string] $CapabilityManifestPath = "packages\org.gamecult.eve.unity-uitoolkit\eve-runtime-capability.json",
+  [string] $OutputPath = "artifacts\eveunity-uitoolkit-release-contract\latest\release-request.json"
+)
+
+$ErrorActionPreference = "Stop"
+
+$projectRoot = Split-Path -Parent $PSScriptRoot
+$absoluteCapabilityPath = if ([System.IO.Path]::IsPathRooted($CapabilityManifestPath)) {
+  $CapabilityManifestPath
+} else {
+  Join-Path $projectRoot $CapabilityManifestPath
+}
+$absoluteOutputPath = if ([System.IO.Path]::IsPathRooted($OutputPath)) {
+  $OutputPath
+} else {
+  Join-Path $projectRoot $OutputPath
+}
+
+if (-not (Test-Path -LiteralPath $absoluteCapabilityPath)) {
+  throw "EveUnity release contract input not found: $absoluteCapabilityPath"
+}
+
+$manifest = Get-Content -LiteralPath $absoluteCapabilityPath -Raw | ConvertFrom-Json
+$releaseContract = $manifest.lifecycle.release.releaseContract
+if ($null -eq $releaseContract) {
+  throw "EveUnity release contract missing lifecycle.release.releaseContract"
+}
+foreach ($field in @("ownerRepo", "packageName", "packageRoot", "versionSource", "tagPattern", "artifactKind", "requestSchema", "requestBuilder", "artifactPattern", "publishProof")) {
+  if (-not $releaseContract.$field) {
+    throw "EveUnity release contract missing $field"
+  }
+}
+if ($releaseContract.ownerRepo -ne "EveUnity") {
+  throw "Unexpected EveUnity release owner: $($releaseContract.ownerRepo)"
+}
+if ($releaseContract.requestSchema -ne "gamecult.eve.runtime_release_request.v1") {
+  throw "Unexpected EveUnity release request schema: $($releaseContract.requestSchema)"
+}
+if ($releaseContract.artifactKind -ne "upm-package") {
+  throw "Unexpected EveUnity release artifact kind: $($releaseContract.artifactKind)"
+}
+
+$builderPath = Join-Path $projectRoot $releaseContract.requestBuilder
+$packagePath = Join-Path $projectRoot $releaseContract.versionSource
+$packageRoot = Join-Path $projectRoot $releaseContract.packageRoot
+foreach ($path in @($builderPath, $packagePath, $packageRoot)) {
+  if (-not (Test-Path -LiteralPath $path)) {
+    throw "EveUnity release contract path not found: $path"
+  }
+}
+
+node --test (Join-Path $projectRoot "tools\eveunity\eveunity-release-contract.test.mjs")
+if ($LASTEXITCODE -ne 0) {
+  throw "EveUnity release contract tests failed with exit code $LASTEXITCODE"
+}
+
+node $builderPath --capability $absoluteCapabilityPath --package $packagePath --output $absoluteOutputPath
+if ($LASTEXITCODE -ne 0) {
+  throw "EveUnity release request builder failed with exit code $LASTEXITCODE"
+}
+if (-not (Test-Path -LiteralPath $absoluteOutputPath)) {
+  throw "EveUnity release request was not written: $absoluteOutputPath"
+}
+
+$request = Get-Content -LiteralPath $absoluteOutputPath -Raw | ConvertFrom-Json
+$packageManifest = Get-Content -LiteralPath $packagePath -Raw | ConvertFrom-Json
+foreach ($expectation in @(
+  @{ field = "schema"; value = "gamecult.eve.runtime_release_request.v1" },
+  @{ field = "ownerRepo"; value = "EveUnity" },
+  @{ field = "repository"; value = "GameCult/EveUnity" },
+  @{ field = "packageName"; value = "org.gamecult.eve.unity-uitoolkit" },
+  @{ field = "version"; value = $packageManifest.version },
+  @{ field = "packageRoot"; value = "packages/org.gamecult.eve.unity-uitoolkit" },
+  @{ field = "versionSource"; value = "packages/org.gamecult.eve.unity-uitoolkit/package.json" },
+  @{ field = "artifactKind"; value = "upm-package" }
+)) {
+  if ($request.($expectation.field) -ne $expectation.value) {
+    throw "EveUnity release request $($expectation.field) expected $($expectation.value) got $($request.($expectation.field))"
+  }
+}
+
+$expectedTagName = $releaseContract.tagPattern.Replace("{version}", $packageManifest.version)
+if ($request.tagName -ne $expectedTagName) {
+  throw "Unexpected EveUnity release tag: $($request.tagName)"
+}
+$expectedArtifactPath = $releaseContract.artifactPattern.Replace("{version}", $packageManifest.version)
+if ($request.artifactPath -ne $expectedArtifactPath) {
+  throw "Unexpected EveUnity release artifact path: $($request.artifactPath)"
+}
+if ($request.dependencies."org.gamecult.eve.surface" -ne $packageManifest.dependencies."org.gamecult.eve.surface") {
+  throw "EveUnity release request lost org.gamecult.eve.surface dependency"
+}
+
+Write-Host "EveUnity release contract smoke passed: $absoluteOutputPath"

scripts/run-runtime-owner-conformance-consumer-smoke.ps1

@@ -108,6 +108,9 @@ node $consumerScript $consumerExport `
   --expect-runtime-lifecycle-pending "unity-uitoolkit:capture:Unity batchmode or editor capture artifact" `
   --expect-runtime-lifecycle-field "unity-uitoolkit:release:releaseContract.packageName:org.gamecult.eve.unity-uitoolkit" `
   --expect-runtime-lifecycle-field "unity-uitoolkit:release:releaseContract.artifactKind:upm-package" `
+  --expect-runtime-lifecycle-field "unity-uitoolkit:release:releaseContract.requestSchema:gamecult.eve.runtime_release_request.v1" `
+  --expect-runtime-lifecycle-field "unity-uitoolkit:release:releaseContract.requestBuilder:tools/eveunity/eveunity-release-contract.mjs" `
+  --expect-runtime-lifecycle-field "unity-uitoolkit:release:releaseContract.artifactPattern:artifacts/eveunity-uitoolkit-release/{version}/org.gamecult.eve.unity-uitoolkit-{version}.tgz" `
   --expect-runtime-lifecycle-field "unity-uitoolkit:release:releaseContract.tagPattern:eveunity-uitoolkit-v{version}" `
   --expect-runtime-lifecycle-field "unity-uitoolkit:release:releaseContract.packageRoot:packages/org.gamecult.eve.unity-uitoolkit" `
   --expect-runtime-lifecycle-field "unity-uitoolkit:test:testContract.runnerKind:unity-editmode-batchmode" `

tools/eveunity/eveunity-release-contract.mjs

@@ -0,0 +1,116 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function buildUnityReleaseRequest({
+  capabilityManifest,
+  packageManifest,
+  capabilityManifestPath = "",
+  packageManifestPath = "",
+  repository = "GameCult/EveUnity",
+} = {}) {
+  if (!capabilityManifest || typeof capabilityManifest !== "object") {
+    throw new Error("capabilityManifest is required");
+  }
+  if (!packageManifest || typeof packageManifest !== "object") {
+    throw new Error("packageManifest is required");
+  }
+
+  const releaseContract = capabilityManifest.lifecycle?.release?.releaseContract;
+  if (!releaseContract) {
+    throw new Error("capability manifest is missing lifecycle.release.releaseContract");
+  }
+
+  if (packageManifest.name !== releaseContract.packageName) {
+    throw new Error(`package name mismatch: expected ${releaseContract.packageName} got ${packageManifest.name || "missing"}`);
+  }
+  if (!packageManifest.version || !/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(packageManifest.version)) {
+    throw new Error(`package version is not a SemVer-compatible release version: ${packageManifest.version || "missing"}`);
+  }
+  if (packageManifest.dependencies && !packageManifest.dependencies["org.gamecult.eve.surface"]) {
+    throw new Error("Unity UI Toolkit package must depend on org.gamecult.eve.surface");
+  }
+
+  const tagName = replaceVersion(releaseContract.tagPattern, packageManifest.version);
+  const artifactPath = replaceVersion(
+    releaseContract.artifactPattern || `artifacts/eveunity-uitoolkit-release/{version}/${releaseContract.packageName}-{version}.tgz`,
+    packageManifest.version,
+  );
+
+  return {
+    schema: releaseContract.requestSchema || "gamecult.eve.runtime_release_request.v1",
+    ownerRepo: releaseContract.ownerRepo,
+    repository,
+    packageName: releaseContract.packageName,
+    displayName: packageManifest.displayName || "",
+    version: packageManifest.version,
+    unity: packageManifest.unity || "",
+    packageRoot: releaseContract.packageRoot,
+    versionSource: releaseContract.versionSource,
+    tagName,
+    artifactKind: releaseContract.artifactKind,
+    artifactPath,
+    publishProof: releaseContract.publishProof,
+    sourceCapabilityManifestPath: capabilityManifestPath,
+    sourcePackageManifestPath: packageManifestPath,
+    dependencies: packageManifest.dependencies || {},
+  };
+}
+
+export function loadJsonFile(filePath) {
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}
+
+export function writeReleaseRequest(request, outputPath) {
+  mkdirSync(path.dirname(outputPath), { recursive: true });
+  writeFileSync(outputPath, `${JSON.stringify(request, null, 2)}\n`, "utf8");
+}
+
+function replaceVersion(pattern, version) {
+  if (!pattern || !pattern.includes("{version}")) {
+    throw new Error(`release pattern must include {version}: ${pattern || "missing"}`);
+  }
+  return pattern.replaceAll("{version}", version);
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (!value.startsWith("--")) continue;
+    const key = value.slice(2);
+    const next = argv[index + 1];
+    if (!next || next.startsWith("--")) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      index += 1;
+    }
+  }
+  return args;
+}
+
+function runCli() {
+  const args = parseArgs(process.argv.slice(2));
+  for (const required of ["capability", "package", "output"]) {
+    if (!args[required]) {
+      throw new Error(`missing required --${required}`);
+    }
+  }
+
+  const request = buildUnityReleaseRequest({
+    capabilityManifest: loadJsonFile(args.capability),
+    packageManifest: loadJsonFile(args.package),
+    capabilityManifestPath: args.capability,
+    packageManifestPath: args.package,
+    repository: args.repository || "GameCult/EveUnity",
+  });
+  writeReleaseRequest(request, args.output);
+  process.stdout.write(`${args.output}\n`);
+}
+
+const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : "";
+const modulePath = fileURLToPath(import.meta.url);
+if (invokedPath === modulePath) {
+  runCli();
+}

tools/eveunity/eveunity-release-contract.test.mjs

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+import { buildUnityReleaseRequest } from "./eveunity-release-contract.mjs";
+
+const capabilityManifest = JSON.parse(readFileSync(new URL("../../packages/org.gamecult.eve.unity-uitoolkit/eve-runtime-capability.json", import.meta.url), "utf8"));
+const packageManifest = JSON.parse(readFileSync(new URL("../../packages/org.gamecult.eve.unity-uitoolkit/package.json", import.meta.url), "utf8"));
+
+test("builds EveUnity UPM release request from package manifest", () => {
+  const request = buildUnityReleaseRequest({
+    capabilityManifest,
+    packageManifest,
+    capabilityManifestPath: "packages/org.gamecult.eve.unity-uitoolkit/eve-runtime-capability.json",
+    packageManifestPath: "packages/org.gamecult.eve.unity-uitoolkit/package.json",
+  });
+
+  assert.equal(request.schema, "gamecult.eve.runtime_release_request.v1");
+  assert.equal(request.ownerRepo, "EveUnity");
+  assert.equal(request.repository, "GameCult/EveUnity");
+  assert.equal(request.packageName, "org.gamecult.eve.unity-uitoolkit");
+  assert.equal(request.version, "0.1.0");
+  assert.equal(request.packageRoot, "packages/org.gamecult.eve.unity-uitoolkit");
+  assert.equal(request.versionSource, "packages/org.gamecult.eve.unity-uitoolkit/package.json");
+  assert.equal(request.tagName, "eveunity-uitoolkit-v0.1.0");
+  assert.equal(request.artifactKind, "upm-package");
+  assert.equal(request.artifactPath, "artifacts/eveunity-uitoolkit-release/0.1.0/org.gamecult.eve.unity-uitoolkit-0.1.0.tgz");
+  assert.equal(request.dependencies["org.gamecult.eve.surface"], "0.1.0");
+});
+
+test("rejects package manifests that do not match the release contract package", () => {
+  const wrongPackage = { ...packageManifest, name: "org.gamecult.eve.wrong" };
+
+  assert.throws(
+    () => buildUnityReleaseRequest({ capabilityManifest, packageManifest: wrongPackage }),
+    /package name mismatch/,
+  );
+});

tools/parity/parity-manifest.json

@@ -1334,11 +1334,17 @@
             "versionSource": "packages/org.gamecult.eve.unity-uitoolkit/package.json",
             "tagPattern": "eveunity-uitoolkit-v{version}",
             "artifactKind": "upm-package",
+            "requestSchema": "gamecult.eve.runtime_release_request.v1",
+            "requestBuilder": "tools/eveunity/eveunity-release-contract.mjs",
+            "artifactPattern": "artifacts/eveunity-uitoolkit-release/{version}/org.gamecult.eve.unity-uitoolkit-{version}.tgz",
             "publishProof": "Tagged UPM release is created from the EveUnity repo and references this package root."
           },
           "evidencePaths": [
             "packages/org.gamecult.eve.unity-uitoolkit/package.json",
             "packages/org.gamecult.eve.unity-uitoolkit/README.md",
+            "tools/eveunity/eveunity-release-contract.mjs",
+            "tools/eveunity/eveunity-release-contract.test.mjs",
+            "scripts/run-eveunity-release-contract-smoke.ps1",
             "scripts/run-aetheria-unity-package-smoke.ps1"
           ],
           "pendingProofs": [

tools/parity/run-parity.mjs

@@ -1342,12 +1342,12 @@ function compareReleaseContract(expected, actual, label) {
   const errors = [];
   if (!expected) return errors;
   if (!actual) return [`${label}:missing`];
-  for (const key of ["ownerRepo", "packageName", "packageRoot", "versionSource", "tagPattern", "artifactKind", "publishProof"]) {
+  for (const key of ["ownerRepo", "packageName", "packageRoot", "versionSource", "tagPattern", "artifactKind", "requestSchema", "requestBuilder", "artifactPattern", "publishProof"]) {
     if ((expected[key] || "") !== (actual[key] || "")) {
       errors.push(`${label}.${key}:expected ${expected[key] || ""} got ${actual[key] || ""}`);
     }
   }
-  for (const key of ["packageRoot", "versionSource"]) {
+  for (const key of ["packageRoot", "versionSource", "requestBuilder"]) {
     if (actual[key] && !existsSync(path.join(repoRoot, actual[key]))) {
       errors.push(`${label}.${key}:${actual[key]}:missing`);
     }